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

项目
05/09/2023

创建、更新或加入会话。

重要提示：
此 URI 方法需要每个请求都有一个 X-Xbl-Contract-Version 104/105 或更高版本的标头元素。

备注
URI 参数
HTTP 状态代码
请求正文
响应正文

备注

此 HTTP/REST 方法创建、加入或更新会话，具体取决于发送的是同一 JSON 请求正文模板的哪个子集。如果成功，则返回一个 MultiplayerSession 对象，其中包含从服务器返回的响应。其中的属性可能与传入的 MultiplayerSession 对象中的属性不同。此方法可由 Microsoft.Xbox.Services.Multiplayer.MultiplayerService.WriteSessionAsync 包装。

会话创建和更新操作将 PUT 与 application/json 正文（表示要应用的更改）一起使用。这些是幂等操作，也就是说，相同更改的多个应用程序没有其他影响。

JSON 请求正文反映了会话数据结构。所有字段和子字段均为可选。

PUT 方法的会话创建或加入模式的有线格式如下所示。

注意：
使用此模式时要小心。无论会话的当前状态如何，都会盲目地应用更新。

PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/00000000-0000-0000-0000-000000000001 HTTP/1.1
         Content-Type: application/json

PUT 方法的会话更新模式的有线格式如下所示。

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 未找到”。此操作支持 If-Match 标头。

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	字符串	会话模板当前实例的名称。会话标识符的第 2 部分。
sessionName	GUID	会话的唯一 ID。会话标识符的第 3 部分。

HTTP 状态代码

该服务返回 HTTP 状态代码，因为它适用于 MPSD。

请求正文

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

成员	类型	说明
constants	对象	与会话模板合并以生成会话常量的只读设置。
properties	对象	更改为合并到会话属性中。
members.me	对象	工作方式与其顶层对应项非常相似的常量和属性。任何 PUT 方法都要求用户是会话的成员，在必要时将添加用户。如果“me”被指定为 null，发起请求的成员将被从会话中删除。
members	对象	表示要添加到会话的用户的其他对象，由从零开始的索引键控。请求中的成员数始终以 0 开头，即使会话已经包含成员。成员按照它们在请求中显示的顺序添加到会话。成员属性只能由其所属的用户设置。
servers	对象	一些值，指示会话的关联服务器参与者集的更新和添加。如果某服务器被指定为 null，系统将从会话中删除该服务器条目。

{
  "properties": {
    "custom": {"KANWE": "MGMSY"},
    "system": {}
  },
  "constants": {
    "custom": {},
    "system": {"visibility": "open"}
  },
  "members": {
    "reserve_0": {
    "constants": {
      "custom": {"type": "leader"},
      "system": {"xuid": "5500461"} }}
   }
}

响应正文

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

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

通过