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

## 备注

此 HTTP/REST 方法为句柄数据创建查询，同时在 “include” 查询字符串中指定会话信息。查询字符串值设计为可扩展的，以支持未来的查询选项，支持逗号分隔的列表，例如 “?include=relatedInfo,session”。此 POST 方法可以由 **Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForUsersAsync** 包装。

此方法的请求正文中的类型字段必须设置为 “activity”。响应正文中的项直接映射到 **Microsoft.Xbox.Services.Multiplayer.MultiplayerActivityDetails** 的属性。

## URI 参数

## 查询字符串参数

可以使用下表中的查询字符串参数来修改查询。

\| **参数**| **类型**| **说明**|
\| --- | --- | --- | --- |
\| keyword| string| 关键字，例如 “foo”，如果要检索会话或模板，则必须在其中找到该关键字。 |
\| xuid| 64 位无符号整数| 要包含在查询中的会话的 XBOX 用户 ID，例如 “123”。默认情况下，用户必须在会话中处于活动状态才能被包括在内。 |
\| reservations| boolean| 为 true 时，包括用户被设置为预留玩家但尚未加入成为活动玩家的会话。此参数仅在查询您自己的会话或以服务器到服务器方式查询特定用户的会话时使用。 |
\| inactive| boolean| 为 true 时，包括用户已接受但未主动参与的会话。用户处于 “ready” 但非 “active” 状态的会话视为不活动。 |
\| private| boolean| 为 true 时，包括专用会话。此参数仅在查询您自己的会话或以服务器到服务器方式查询特定用户的会话时使用。 |
\| visibility| string| 会话的可见性状态。可能的值由 **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 状态代码。

## 请求正文

### 示例请求

要获取用户 “favorites” 社交图谱的所有活动，POST 正文如下所示：

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

```

## 响应正文

结果作为句柄结构数组返回，每个句柄中嵌入一个唯一 ID。特定的会话信息在 **relatedInfo** 对象中返回。请注意，此 URI 上的常规 POST 方法不会返回此信息。

### 示例响应

```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,
		}
	}]
}

```

## 另请参阅

##### 上级

[/handles/query](https://devdocs.xbox.com/zh-CN/reference/live/rest/uri/sessiondirectory/uri-handlesquery)


## Related topics

- [Multiplayer session browse](https://devdocs.xbox.com/services/xbox-services/multiplayer/concepts/live-session-browse.md)
- [GDK Commerce Systems Overview](https://devdocs.xbox.com/publishing/xstore-commerce/xstore-overview.md)
- [PAGE Guideline - Supplemental Info](https://devdocs.xbox.com/build/game-principles/accessibility/page/page-checklists.md)
- [Query](https://devdocs.xbox.com/pt-BR/reference/system/dstorage/interfaces/IDStorageQueueX/methods/idstoragequeuex_query.md)