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 でラップすることができます。

セッションの作成および更新の操作では、適用する変更を表すアプリケーション/json 本文と共に PUT を使用します。操作はべき等です。同じ変更を複数適用しても追加の効果はありません。

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 Not Found が返される点です。この操作は、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	サービス構成 ID (SCID)。セッション識別子の 1 番目の部分です。
sessionTemplateName	文字列	セッションテンプレートの現在のインスタンスの名前です。セッション識別子の 2 番目の部分です。
sessionName	GUID	セッションの一意の ID。セッション識別子の 3 番目の部分です。

HTTP ステータスコード

サービスは、MPSD に適用される HTTP ステータスコードを返します。

リクエストの本文

以下に、セッションの作成または結合を行う要求本文の例を示します。要求本文の以下のメンバーは省略可能です。その他に指定可能なメンバーはすべて、要求内では使用できません。

メンバー	種類	説明
constants	オブジェクト	セッションの定数を作成するためにセッションテンプレートとマージされる読み取り専用設定。
properties	オブジェクト	セッションのプロパティにマージされる変更。
members.me	オブジェクト	最上位の定数およびプロパティとほとんど同じ働きをする定数およびプロパティ。 PUT メソッドでは、ユーザーがセッションのメンバーである必要があり、必要に応じてユーザーを追加します。 "me" が null として指定されている場合、その要求を行うメンバーはセッションから削除されます。
members	オブジェクト	セッションに追加するユーザー (0 から始まるインデックスをキーとする) を表すその他のオブジェクト。セッションに既にメンバーが含まれている場合でも、要求内のメンバーの番号は常に 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": { }
      }
  }
}

次の方法で共有

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

解説

URI パラメーター

HTTP ステータスコード

リクエストの本文

応答の本文

関連項目

親

その他のリソース

次の方法で共有

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

解説

URI パラメーター

HTTP ステータス コード

リクエストの本文

応答の本文

関連項目

親

その他のリソース

HTTP ステータスコード