POST (/handles/query)
创建会话句柄查询。
重要提示:
此方法由 2015 多人游戏使用,仅适用于该多人游戏版本及更高版本。 它适用于模板协定 104/105 或更高版本,并且每个请求都需要一个 X-Xbl-Contract-Version 104/105 或更高版本的标头元素。
此 HTTP/REST 方法仅为句柄数据创建查询,不含任何会话信息。 它可由 Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForSocialGroupAsync 包装。
此方法的请求正文中的类型字段必须为“活动”。 响应正文中的项目直接映射到 MultiplayerActivityDetails 的属性。
可使用下一个表中的查询字符串参数修改查询。
参数 | Type | Description |
---|---|---|
keyword | 字符串 | 一个关键字(例如“foo”),如果要检索会话或模板,必须在会话或模板中找到该关键字。 |
xuid | 64 位无符号整数 | 要包含在查询中的会话的 Xbox 用户 ID,例如“123”。 默认情况下,用户必须在要包括的会话中处于活动状态。 |
reservations | 布尔值 | 如果为 true,则包括将用户设置为保留玩家但并未加入成为活动玩家的会话。 仅在查询你自己的会话,或对特定用户的会话进行服务器到服务器查询时才使用此参数。 |
inactive | 布尔值 | 如果为 true,则包括用户已接受但没有在其中主动进行游戏的会话。 用户处于“就绪”状态但未“活动”的会话算作非活动会话。 |
private | 布尔值 | 如果为 true,则包括专用会话。 仅在查询你自己的会话,或对特定用户的会话进行服务器到服务器查询时才使用此参数。 |
visibility | 字符串 | 会话的可见性状态。 可能值由 MultiplayerSessionVisibility 定义。 如果此参数设置为“open”,查询应仅包括打开的会话。 如果设置为“private”,则 private 参数也必须设置为 true。 |
版本 | 32 位有符号整数 | 应包括的最大会话版本。 例如,值为 2 表明应只包括主会话版本为 2 或更低的会话。 版本号必须小于或等于请求的协定版本 mod 100。 |
take | 32 位有符号整数 | 要检索的最大会话数。 此数字必须在 0 到 100 之间。 |
将 private 或 reservations 设置为 true 需要拥有对会话的服务器级访问权限。 或者,这些设置需要调用方的 XUID 声明以匹配 URI 中的 XUID 筛选器。 否则,返回 HTTP/403 状态代码(无论是否确实存在任何此类会话)。
若要获取用户“收藏夹”社交图片的所有活动,请求正文应如下所示:
{
"type": "activity",
"scid": "B5B1F71F-A328-4371-89E0-C3AD222D0E92" // optional filter on scid
"owners": {
"people": {
"moniker": "favorites",
"monikerXuid": "3210"
}
}
}
句柄以句柄结构数组的形式检索,每个结构中嵌入一个唯一 ID。
{
"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",
{
"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",
}
}]
}