Skip to main content

POST (/users/batch)

获取一批用户的在线状态。 这些 URI 的域为 userpresence.xboxlive.com。

备注

任何希望了解一批用户在线状态信息的客户端、服务或标题都应使用此方法。 此批处理请求的响应可按深度和路径进行筛选。使用者可以借此查询并显示一组用户的在线状态。此 API 上的筛选器在同一属性内以 OR 方式起作用,而在不同属性之间则以 AND 方式起作用。

授权

隐私设置对资源的影响

此方法始终返回 200 OK,但可能不会在响应正文中返回内容。 | 请求用户 | 目标用户的隐私设置 | 行为 | | --- | --- | --- | --- | --- | --- | --- | | me | - | 200 OK | | friend | everyone | 200 OK | | friend | friends only | 200 OK | | friend | blocked | 200 OK | | non-friend user | everyone | 200 OK | | non-friend user | friends only | 200 OK | | non-friend user | blocked | 200 OK | | third-party site | everyone | 200 OK | | third-party site | friends only | 200 OK | | third-party site | blocked | 200 OK |

必需的请求标头

| 标头 | 类型 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Authorization | string | HTTP 身份验证的身份验证凭据。示例值:“XBL3.0 x=<userhash>;<token>”。 | | x-xbl-contract-version | string | 此请求应指向的 XBOX LIVE 服务的生成名称/编号。仅在验证标头的有效性、身份验证令牌中的声明等的有效性之后,请求才会路由到该服务。示例值:3、vnext。 | | Accept | string | 可接受的 Content-Type。在线状态服务仅支持 application/json,但必须在标头中指定。 | | Accept-Language | string | 响应中字符串的可接受区域设置。示例值:en-US。 | | Host | string | 服务器的域名。示例值:presencebeta.xboxlive.com。 | | Content-Length | string | 请求正文的长度。示例值:312。 |

可选的请求标头

| 标头 | 类型 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | X-RequestedServiceVersion | | 此请求应指向的 XBOX LIVE 服务的生成名称/编号。仅在验证标头的有效性、身份验证令牌中的声明等的有效性之后,请求才会路由到该服务。默认值:1。 |

请求正文

必需成员

| 成员 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | users | 你希望了解其在线状态的用户的 XUID 列表,一次最多 1100 个 XUID。 |

可选成员

| 成员 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | deviceTypes | 你想了解的用户所使用的设备类型列表。如果数组为空,则默认为所有可能的设备类型(即不筛选任何设备)。 | | titles | 你想了解其用户的设备类型列表。如果数组为空,则默认为所有可能的标题(即不筛选任何标题)。 | | level | 可能的值:
  • user - 获取用户节点
  • device - 获取用户和设备节点
  • title - 获取标题级基本信息
  • all - 获取丰富在线状态信息、媒体信息或两者

默认为 “title”。 | | onlineOnly | 如果此属性为 true,则批处理操作将筛选掉离线用户(包括隐身用户)的记录。如果未提供,将同时返回在线和离线用户。 |

禁止的成员

请求中禁止所有其他成员。

示例请求

响应正文

示例响应

此方法返回 PresenceRecord。

另请参阅

父主题
/users/batch
Last modified on October 19, 2026