> ## 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)

## 备注

此 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": { } }

```

## URI 参数

\| 参数| 类型| 说明|
\| --- | --- | --- | --- | --- |
\| scid| GUID| 服务配置标识符 (SCID)。会话标识符的第 1 部分。|
\| sessionTemplateName| string| 会话模板当前实例的名称。会话标识符的第 2 部分。|
\| sessionName| GUID| 会话的唯一 ID。会话标识符的第 3 部分。|

## HTTP 状态代码

服务返回适用于 MPSD 的 HTTP 状态代码。

## 请求正文

下面是用于创建或加入会话的请求正文示例。请求正文的以下成员是可选的。请求中禁止使用所有其他可能的成员。

\| 成员| 类型| 说明|
\| --- | --- | --- | --- | --- | --- | --- | --- |
\| 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"} }}
   }
}

```

## 响应正文

用于创建或加入会话的响应正文示例：

```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": { }
      }
  }
}

```

## 另请参阅

##### 上级

[/serviceconfigs/{scid}/sessiontemplates/{sessionTemplateName}/sessions/{sessionName}](https://devdocs.xbox.com/zh-CN/reference/live/rest/uri/sessiondirectory/uri-serviceconfigsscidsessiontemplatessessiontemplatenamesessionssessionname)


## Related topics

- [XblMultiplayerSessionReferenceUri](https://devdocs.xbox.com/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessionreferenceuri.md)
- [XblMultiplayerSessionReference](https://devdocs.xbox.com/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayersessionreference.md)