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

# POST (/handles/query?include=relatedInfo)

> POST (/handles/query?include=relatedInfo)

# POST (/handles/query?include=relatedInfo)

建立包含相關工作階段資訊的工作階段控制代碼查詢。

> **重要：**\
> 此方法由 2015 多人遊戲使用，僅適用於該多人遊戲版本及更新版本。其適用於範本合約 104/105 或更新版本，且每個要求都需要 X-Xbl-Contract-Version: 104/105 或更新版本的標頭元素。

* [備註](#ID4ET)
* [URI 參數](#ID4ECB)
* [查詢字串參數](#ID4EPB)
* [HTTP 狀態碼](#ID4EAF)
* [要求本文](#ID4EHF)
* [回應本文](#ID4EZF)

<a id="ID4ET" />

## 備註

此 HTTP/REST 方法會建立控制代碼資料的查詢，並包含 "include" 查詢字串中指定的工作階段資訊。查詢字串值設計為可擴充，以支援未來的查詢選項，並支援以逗號分隔的清單，例如 "?include=relatedInfo,session"。此 POST 方法可由 **Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForUsersAsync** 包裝。

此方法要求本文中的 type 欄位必須設為 "activity"。回應本文中的項目會直接對應至 **Microsoft.Xbox.Services.Multiplayer.MultiplayerActivityDetails** 的屬性。

<a id="ID4ECB" />

## URI 參數

<a id="ID4EPB" />

## 查詢字串參數

您可以使用下表中的查詢字串參數修改查詢。

\| <b>參數</b>| <b>類型</b>| <b>描述</b>|
\| --- | --- | --- | --- |
\| keyword| string| 關鍵字，例如 "foo"，工作階段或範本中必須包含此關鍵字才會被擷取。 |
\| xuid| 64 位元不帶正負號的整數| 要包含在查詢中之工作階段的 XBOX 使用者識別碼，例如 "123"。根據預設，使用者必須在工作階段中處於作用中狀態，該工作階段才會被包含。 |
\| reservations| boolean| True 表示包含使用者被設為保留玩家但尚未加入成為作用中玩家的工作階段。只有在查詢您自己的工作階段，或以伺服器對伺服器方式查詢特定使用者的工作階段時，才會使用此參數。 |
\| inactive| boolean| True 表示包含使用者已接受但未在積極遊玩的工作階段。使用者處於 "ready" 但非 "active" 狀態的工作階段會視為非作用中。 |
\| private| boolean| True 表示包含私人工作階段。只有在查詢您自己的工作階段，或以伺服器對伺服器方式查詢特定使用者的工作階段時，才會使用此參數。 |
\| visibility| string| 工作階段的可見性狀態。可能的值由 <b>Microsoft.Xbox.Services.Multiplayer.MultiplayerSessionVisibility</b> 定義。如果此參數設為 "open"，查詢應只包含開放的工作階段。如果設為 "private"，則 <i>private</i> 參數必須設為 true。 |
\| version| 32 位元帶正負號的整數| 應包含的最大工作階段版本。例如，值為 2 表示只應包含主要工作階段版本為 2 或以下的工作階段。版本號碼必須小於或等於要求的合約版本除以 100 的餘數。 |
\| take| 32 位元帶正負號的整數| 要擷取的工作階段數目上限。此數字必須介於 0 到 100 之間。 |

將 *private* 或 *reservations* 設為 true 時，需要具備工作階段的伺服器層級存取權。或者，這些設定需要呼叫者的 XUID 宣告符合 URI 中的 XUID 篩選條件。否則，無論是否確實存在此類工作階段，都會傳回 HTTP/403 狀態碼。

<a id="ID4EAF" />

## HTTP 狀態碼

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

<a id="ID4EHF" />

## 要求本文

<a id="ID4ENF" />

### 範例要求

若要取得使用者 "favorites" 社交圖譜的所有活動，POST 本文如下所示：

```cpp theme={null}
{
  "type": "activity",
  "scid": "B5B1F71F-A328-4371-89E0-C3AD222D0E92"  // optional filter on scid
  "owners": {
     "people": {
       "moniker": "favorites",
       "monikerXuid": "3210"
     }
  }
}

```

<a id="ID4EZF" />

## 回應本文

結果會以控制代碼結構陣列的形式傳回，每個控制代碼中都內嵌唯一識別碼。特定的工作階段資訊會在 **relatedInfo** 物件中傳回。請注意，此 URI 上的一般 POST 方法不會傳回此資訊。

<a id="ID4EDG" />

### 範例回應

```cpp theme={null}
{
	"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,
		}
	}]
}

```

<a id="ID4ENG" />

## 另請參閱

<a id="ID4EPG" />

##### 上層

[/handles/query](/zh-TW/reference/live/rest/uri/sessiondirectory/uri-handlesquery)


## Related topics

- [Multiplayer session browse](/services/xbox-services/multiplayer/concepts/live-session-browse.md)
- [GDK Commerce Systems Overview](/publishing/xstore-commerce/xstore-overview.md)
- [PAGE · Pre-planning and post-event accessibility checklists](/build/game-principles/accessibility/page/page-checklists.md)
- [XR-014 Player data and personal information](/publishing/certification/xr/xr-014.md)
- [Multiplayer Session Directory overview](/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md)