> ## 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 /titles/{titleId}/activities/query

> Get Activity Batch

# Get Activity Batch

获取用户列表的一批多玩家活动。

此 API 允许客户端和服务获取一组用户的批量活动。

此 API 可以返回部分结果;任意给定用户都会拥有其完整的活动集,但某些用户可能完全没有活动。如果我们为一部分用户查找到了活动,则返回这些活动。对于未找到活动的用户,我们为该用户返回一个空列表。对于由于内部错误无法获取活动的用户,我们为该用户返回 null;客户端应重试调用。简而言之,一个用户可以拥有一个活动列表、一个空列表或 null。

```http theme={null}
POST /titles/{titleId}/activities/query
```

## URI 参数

| 参数 | 位置 | 是否必需 | 类型 | 说明 |
| - | - | - | - | - |
| titleId | path | TRUE | integer | 发送请求所针对的游戏的 titleId。 |

## 请求正文

| 名称 | 是否必需 | 类型 | 说明 |
| - | - | - | - |
| users | TRUE | string\[] | 需要检索活动信息的用户 ID。最多支持 30 个用户。 |

## 请求标头

| 名称 | 是否必需 | 类型 | 说明 |
| - | - | - | - |
| Authorization | TRUE | integer | 调用方必须以 XBL 3.0 授权格式提供 XToken。例如,Authorization: XBL3.0 x=2553948354698;>encrypted token \<) |
| Content-Type | TRUE | string | ContentType 必须设置为 application/json |

## 响应

| 名称 | 类型 | 说明 |
| - | - | - |
| 200 OK | [GetActivityBatchResponse](#getactivitybatchresponse) | 返回对象包含每个用户的活动列表。如果用户没有当前活动,该用户的活动列表将为空。如果获取用户活动时出现服务问题,该用户的活动列表将为 null。 |
| 400 Bad Request | [ErrorResponse](#errorresponse) | 处理请求时发生错误。可能的错误代码:“InvalidRequest - The request payload is invalid.”、“AuthorizationError: The caller is not allowed to access the resource.” |
| 其他状态代码 | [ThrottledEntity](#throttledentity) | 请求过多。标头 Retry-After: integer |

## 定义

* [ErrorResponse](#errorresponse)
* [GetActivityBatchRequest](#getactivitybatchrequest)
* [GetActivityBatchResponse](#getactivitybatchresponse)
* [GetActivityResponse](#getactivityresponse)
* [JoinRestriction](#joinrestriction)
* [Platform](#platform)
* [ThrottledEntity](#throttledentity)
* [UserActivity](#useractivity)

### ErrorResponse

| 名称 | 类型 | 说明 |
| - | - | - |
| debugMessage | string | 可用于调试的、人类可读的错误消息版本。 |
| errorCode | string | 错误代码枚举。 |

### GetActivityBatchRequest

| 名称 | 类型 | 说明 |
| - | - | - |
| users | string\[] | 需要检索活动信息的用户 ID。最多支持 30 个用户。 |

### GetActivityBatchResponse

| 名称 | 类型 | 说明 |
| - | - | - |
| userActivities | [UserActivity](#useractivity)\[] | |

### GetActivityResponse

| 名称 | 类型 | 说明 |
| - | - | - |
| connectionString | string | 连接字符串是传递给正在连接的客户端以加入游戏的对象。连接字符串通常包含服务器 IP 之类的信息,以使加入的用户能够进行连接。连接字符串的长度限制为 512 个字符。 |
| currentPlayers | integer | 已经与该用户一起在多玩家活动中游戏的玩家数。 |
| groupId | string | 用于将作为同一场游戏一部分进行游戏的所有用户分组的唯一标识符。 |
| joinRestriction | [JoinRestriction](#joinrestriction) | 用于设置谁可以加入当前玩家的选项。 |
| maxPlayers | integer | 当前活动中可以与此玩家一起游戏的最大玩家数。 |
| platform | [Platform](#platform) | |
| sequenceNumber | string | 这是单调递增数字 (ulong) 的字符串表示形式,客户端必须为每个请求传递此值。它用于保证活动更新的顺序。sequenceNumber 的一个很好示例是客户端的 unix 时间,因为它保证是递增的。必须大于 0,且不能大于最大 ulong 值。 |
| titleId | integer | 请求活动的游戏的 titleId。 |

### JoinRestriction

| 名称 | 类型 | 说明 |
| - | - | - |
| Followed | string | |
| InviteOnly | string | |
| Public | string | |

### Platform

| 名称 | 类型 | 说明 |
| - | - | - |
| Android | string | |
| IOS | string | |
| Nintendo | string | |
| PlayStation | string | |
| Scarlett | string | |
| Win32 | string | |
| WindowsOneCore | string | |
| XboxOne | string | |

### ThrottledEntity

| 名称 | 类型 | 说明 |
| - | - | - |
| currentRequests | string | 当前请求数——并发或速率。 |
| debugMessage | string | 可用于调试的、人类可读的限流消息版本。 |
| limitType | string | 限制类型,即并发或速率。 |
| maxRequests | string | 允许的最大请求数——并发或速率。 |
| periodInSeconds | string | 超出速率或并发限制时适用的以秒为单位的时段。 |
| version | string | 当前限流合约版本。 |

### UserActivity

| 名称 | 类型 | 说明 |
| - | - | - |
| activities | [GetActivityResponse](#getactivityresponse)\[] | |
| userId | string | |


## Related topics

- [XblMultiplayerActivityGetActivityAsync](https://devdocs.xbox.com/fr/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityasync.md)
- [Activities](https://devdocs.xbox.com/services/xbox-services/multiplayer/mpa/concepts/live-mpa-activities.md)