> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PUT (/serviceconfigs/{scid}/sessiontemplates/{sessionTemplateName}/sessions/{sessionName})

> PUT (/serviceconfigs/{scid}/sessiontemplates/{sessionTemplateName}/sessions/{sessionName})

# PUT (/serviceconfigs/{scid}/sessiontemplates/{sessionTemplateName}/sessions/{sessionName})

建立、更新或加入工作階段。

> **重要：**\
> 此 URI 方法要求每個要求都必須包含 X-Xbl-Contract-Version: 104/105 或更新版本的標頭元素。

* [備註](#ID4ET)
* [URI 參數](#ID4EYB)
* [HTTP 狀態碼](#ID4EFC)
* [要求本文](#ID4EOC)
* [回應本文](#ID4E4C)

<a id="ID4ET" />

## 備註

此 HTTP/REST 方法會根據所傳送之相同 JSON 要求本文範本的子集，建立、加入或更新工作階段。成功時，會傳回 **MultiplayerSession** 物件，其中包含從伺服器傳回的回應。其中的屬性可能與傳入之 **MultiplayerSession** 物件中的屬性不同。此方法可由 **Microsoft.Xbox.Services.Multiplayer.MultiplayerService.WriteSessionAsync** 包裝。

工作階段建立和更新作業使用 PUT，並搭配代表要套用之變更的 application/json 本文。這些作業具有等冪性，也就是說，多次套用相同的變更不會產生額外的效果。

JSON 要求本文反映工作階段資料結構。所有欄位和子欄位都是選用的。

PUT 方法之工作階段建立或加入模式的網路傳輸格式如下所示。

> **注意：**\
> 使用此模式時請小心。無論工作階段目前的狀態為何，都會直接套用更新。

```cpp theme={null}
PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/00000000-0000-0000-0000-000000000001 HTTP/1.1
         Content-Type: application/json

```

PUT 方法之工作階段更新模式的網路傳輸格式如下所示。

```cpp theme={null}
PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/00000000-0000-0000-0000-000000000001 HTTP/1.1
         Content-Type: application/json

```

用來更新工作階段屬性之 PUT 方法的網路傳輸格式如下所示。這相當於對工作階段 URI 執行 PUT 作業，且本文中只有下列物件作為屬性。差別在於，如果工作階段不存在，此作業會傳回錯誤碼 404 Not Found。此作業支援 If-Match 標頭。

```cpp theme={null}
PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/00000000-0000-0000-0000-000000000001/properties HTTP/1.1
         Content-Type: application/json

         { "system": { }, "custom": { } }

```

<a id="ID4EYB" />

## URI 參數

\| 參數| 類型| 描述|
\| --- | --- | --- | --- | --- |
\| scid| GUID| 服務設定識別碼 (SCID)。工作階段識別碼的第 1 部分。|
\| sessionTemplateName| string| 工作階段範本目前執行個體的名稱。工作階段識別碼的第 2 部分。|
\| sessionName| GUID| 工作階段的唯一識別碼。工作階段識別碼的第 3 部分。|

<a id="ID4EFC" />

## HTTP 狀態碼

服務會傳回適用於 MPSD 的 HTTP 狀態碼。

<a id="ID4EOC" />

## 要求本文

以下是用於建立或加入工作階段的範例要求本文。要求本文的下列成員為選用。要求中禁止使用所有其他可能的成員。

\| 成員| 類型| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- |
\| constants| object| 唯讀設定，會與工作階段範本合併以產生工作階段的常數。 |
\| properties | object | 要合併至工作階段屬性的變更。|
\| members.me | object| 常數和屬性，運作方式與其最上層對應項目非常類似。任何 PUT 方法都要求使用者必須是工作階段的成員，並會視需要新增使用者。如果 "me" 指定為 null，則會從工作階段移除提出要求的成員。 |
\| members | object| 代表要新增至工作階段之使用者的其他物件，以從零開始的索引作為索引鍵。要求中的成員編號一律從 0 開始，即使工作階段已包含成員也一樣。成員會依照其在要求中出現的順序新增至工作階段。成員屬性只能由其所屬的使用者設定。 |
\| servers | object| 指出對工作階段相關聯伺服器參與者集合之更新和新增的值。如果伺服器指定為 null，則會從工作階段移除該伺服器項目。 |

```cpp theme={null}
{
  "properties": {
    "custom": {"KANWE": "MGMSY"},
    "system": {}
  },
  "constants": {
    "custom": {},
    "system": {"visibility": "open"}
  },
  "members": {
    "reserve_0": {
    "constants": {
      "custom": {"type": "leader"},
      "system": {"xuid": "5500461"} }}
   }
}

```

<a id="ID4E4C" />

## 回應本文

建立或加入工作階段的範例回應本文：

```cpp theme={null}
{
  "contractVersion": 104,
  "correlationId": "0FE81338-EE96-46E3-A3B5-2DBBD6C41C3B",
  "nextTimer": "2009-06-15T13:45:30.0900000Z",

  "initializing": {
    "stage": "measuring",
    "stageStartTime": "2009-06-15T13:45:30.0900000Z",
    "episode": 1
  },

  "hostCandidates": [ "ab90a362", "99582e67" ],

  "constants": {
    "system": {"visibility": "open"},
    "custom": {}
  },

  "properties": {
     "system": { "turn": [] },
     "custom": { "myProperty": "myValue" }
  },

  "members": {
      "1": {
        "properties": {
        "system": { },
        "custom": { }
      },

      "constants": {
        "system": { "xuid": "5500461" },
        "custom": { }
      }

      "gamertag": "stacy",
      "deviceToken": "9f4032ba7",
      "reserved": true,
      "activeTitleId": "8397267",
      "joinTime": "2009-06-15T13:45:30.0900000Z",
      "turn": true,
      "initializationFailure": "latency",
      "initializationEpisode": 1,
      "next": 4
    },
  },

  "membersInfo": {
      "first": 1,
      "next": 4,
      "count": 1,
      "accepted": 0
  },

  "servers": {
      "name": {
        "constants": { },
        "properties": { }
      }
  }
}

```

<a id="ID4EID" />

## 另請參閱

<a id="ID4EKD" />

##### 上層

[/serviceconfigs/{scid}/sessiontemplates/{sessionTemplateName}/sessions/{sessionName}](/zh-TW/reference/live/rest/uri/sessiondirectory/uri-serviceconfigsscidsessiontemplatessessiontemplatenamesessionssessionname)


## Related topics

- [XblMultiplayerSessionReferenceUri](/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessionreferenceuri.md)
- [XblMultiplayerSessionReference](/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessionreference.md)