POST (/handles/query?include=relatedInfo)
関連するセッション情報が含まれるセッション ハンドルに対してクエリを作成します。
重要:
このメソッドは、2015 Multiplayer によって使用され、そのバージョン以降のマルチプレイヤーにのみ適用されます。 これは 104/105 以降のテンプレート コントラクトで使用するためのもので、すべての要求でヘッダー要素 X-Xbl-Contract-Version: に 104/105 以降を指定する必要があります。
解説
この HTTP/REST メソッドは、クエリ文字列 "include" で指定されたセッション情報を使用して、ハンドル データに対するクエリを作成します。 クエリ文字列の値は、たとえば "?include=relatedInfo,session" のように、コンマで区切られた一覧をサポートしており、将来のクエリ オプションをサポートするために拡張可能なように設計されています。 POST メソッドは、Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForUsersAsync でラップすることができます。
このメソッドの要求本文では、"type" フィールドを "activity" に設定する必要があります。 応答本文内の項目は、Microsoft.Xbox.Services.Multiplayer.MultiplayerActivityDetails のプロパティに直接対応しています。
URI パラメーター
クエリ文字列パラメーター
クエリは、次の表に示すクエリ文字列パラメーターを使用して変更できます。
| パラメーター | Type | 説明 |
|---|---|---|
| キーワード | 文字列 | 取得される場合にセッションまたはテンプレート内に含まれている必要があるキーワード (例: "foo")。 |
| xuid | 64 ビット符号なし整数 | クエリに含めるセッションの Xbox ユーザー ID (例: "123")。 既定では、結果に含まれるユーザーはセッション内でアクティブである必要があります。 |
| reservations | ブール値 | ユーザーが予約済みプレイヤーとして設定されているが、まだ参加しておらずアクティブ プレイヤーになっていないセッションを含める場合は true。 このパラメーターは、自分自身のセッションをクエリするとき、または特定ユーザーのセッションをサーバー間でクエリするときにのみ使用されます。 |
| inactive | ブール値 | ユーザーが受け入れたがアクティブにプレイしていないセッションを含める場合は true。 ユーザーが "準備完了" しているが "アクティブ" ではないセッションは非アクティブとしてカウントされます。 |
| private | ブール値 | プライベート セッションを含める場合は true。 このパラメーターは、自分自身のセッションをクエリするとき、または特定ユーザーのセッションをサーバー間でクエリするときにのみ使用されます。 |
| visibility | 文字列 | セッションの表示状態。 設定できる値は Microsoft.Xbox.Services.Multiplayer.MultiplayerSessionVisibility に定義されています。 このパラメーターを "open" に設定した場合、そのクエリには開いているセッションのみが含まれます。 "private" に設定する場合は、private パラメーターを true に設定する必要があります。 |
| version | 32 ビット符号付き整数 | 含める必要があるセッションの最大バージョン。 たとえば、値が 2 の場合、セッションのメジャー バージョンが 2 以下のセッションのみを含めることを指定します。 バージョン番号は、要求のコントラクト バージョンを 100 で割った余り以下でなければなりません。 |
| take | 32 ビット符号付き整数 | 取得するセッションの最大数。 この数は、0 から 100 までの範囲になければなりません。 |
private または reservations を true に設定するには、セッションへのサーバー レベルのアクセスが必要です。 または、これらの設定には、呼び出し元の XUID クレームが URI の XUID フィルターと一致することが必要です。 それ以外の場合、そのようなセッションが実際に存在するかどうかにかかわらず、HTTP/403 ステータス コードが返されます。
HTTP ステータス コード
サービスは、MPSD に適用される HTTP ステータス コードを返します。
リクエストの本文
サンプル要求
ユーザーの "お気に入り" ソーシャル グラフのアクティビティをすべて取得する場合、POST 本文は次のようになります。
{
"type": "activity",
"scid": "B5B1F71F-A328-4371-89E0-C3AD222D0E92" // optional filter on scid
"owners": {
"people": {
"moniker": "favorites",
"monikerXuid": "3210"
}
}
}
応答の本文
結果は、各ハンドルに一意の ID が埋め込まれた、ハンドルの構造体の配列として返されます。 特定のセッションの情報は、relatedInfo オブジェクトで返されます。 この情報は、この URI に対する通常の POST メソッドでは返されないことに注意してください。
サンプル応答
{
"results": [{
"id": "11111111-ebe0-42da-885f-033860a818f6",
"type": "activity",
"version": 1,
"sessionRef": {
"scid": "8dfb0100-ebe0-42da-885f-033860a818f6",
"templateName": "party",
"name": "e3a836aeac6f4cbe9bcab985494d3175"
},
"titleId": "1234567",
"ownerXuid": "3212",
// Only if ?include=relatedInfo
"relatedInfo": {
"visibility": "open",
"joinRestriction": "followed",
"closed": true,
"maxMembersCount": 8,
"membersCount": 4,
}
},
{
"id": "11111111-ebe0-42da-885f-033860a818f7",
"type": "activity",
"version": 1,
"sessionRef": {
"scid": "8dfb0100-ebe0-42da-885f-033860a818f6",
"templateName": "TitleStorageTestDefault",
"name": "795fcaa7-8377-4281-bd7e-e86c12843632"
},
"titleId": "1234567",
"ownerXuid": "3212",
// Only if ?include=relatedInfo
"relatedInfo": {
"visibility": "open",
"joinRestriction": "followed",
"closed": false,
"maxMembersCount": 8,
"membersCount": 4,
}
}]
}