POST (/users/batch)

项目
05/09/2023

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

备注
授权
隐私设置对资源的影响
必需请求标头
可选请求标头
请求正文
响应正文

备注

希望了解一批用户的状态信息的任何客户端、服务或游戏均应该使用此方法。

此批处理请求的响应可以按深度和路径筛选。使用者可使用它来了解并显示一组用户的状态。此 API 上的筛选器在属性中发挥 OR 的作用，但在各个属性之间则充当 AND。

授权

类型	必需	说明	缺少时的响应
XUID	是	调用方的 Xbox 用户 ID (XUID)	403 已禁止

隐私设置对资源的影响

此方法始终返回 200 OK，但可能不会在响应正文中返回内容。

请求用户	目标用户的隐私设置	行为
我	-	200 OK
好友	所有人	200 OK
好友	仅好友	200 OK
好友	已阻止	200 OK
非好友用户	所有人	200 OK
非好友用户	仅好友	200 OK
非好友用户	已阻止	200 OK
第三方站点	所有人	200 OK
第三方站点	仅好友	200 OK
第三方站点	已阻止	200 OK

必需请求标头

标头	类型	说明
授权	字符串	HTTP 身份验证的身份验证凭据。示例值：“XBL3.0 x=<userhash>;<token>”。
x-xbl-contract-version	字符串	此请求应定向到的 Xbox LIVE 服务的版本名称/版本号。在验证标头的有效性、身份验证令牌中的声明等信息之后，请求将仅路由到该服务。示例值：3，vnext。
Accept	字符串	可接受的 Content-Type。仅“状态”支持的一个类型是 application/json，但必须在标头中指定。
Accept-Language	字符串	响应中字符串的可接受区域设置。示例值：en-US。
主机	字符串	服务器域名。示例值：presencebeta.xboxlive.com。
Content-Length	字符串	请求正文的长度。示例值：312。

可选请求标头

标头	类型	说明
X-RequestedServiceVersion		此请求应定向到的 Xbox LIVE 服务的版本名称/版本号。在验证标头的有效性、身份验证令牌中的声明等信息之后，请求将仅路由到该服务。默认值：1。

请求正文

必需成员

成员	说明
用户	列出你想要了解其状态的用户的 XUID，一次最多 1100 个 XUID。

可选成员

成员	说明
deviceTypes	你想要了解的用户使用的设备类型的列表。如果数组留空，将默认为所有可能的设备类型（即，不会筛选掉任何类型）。
游戏	你想要了解的用户的设备类型的列表。如果数组留空，将默认为所有可能的游戏（即，不会筛选掉任何游戏）。
级别	可能值： user - 获取用户节点 device - 获取用户和设备节点 title - 获取基本游戏级别信息 all - 获取丰富显示状态信息、媒体信息或全部获取默认值为“title”。
onlineOnly	如果此属性为 true，批处理操作将筛选掉离线用户（包括隐藏用户）的记录。如果未提供，将同时返回在线和离线用户。

禁止成员

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

示例请求

{
  users:
  [
    "1234567890",
    "4567890123",
    "7890123456"
  ]
}

响应正文

示例响应

此方法返回 PresenceRecord。

{
  xuid:"0123456789",
  state:"online",
  devices:
  [{
    type:"D",
    titles:
    [{
      id:"12341234",
      name:"Contoso 5",
      state:"active",
      placement:"fill",
      timestamp:"2012-09-17T07:15:23.4930000",
      activity:
      {
        richPresence:"Team Deathmatch on Nirvana"
      }
    },
    {
      id:"12341235",
      name:"Contoso Waypoint",
      timestamp:"2012-09-17T07:15:23.4930000",
      placement:"snapped",
      state:"active",
      activity:
      {
        richPresence:"Using radar"
      }
    }]
  },
  {
    type:W8,
    titles:
    [{
      id:"23452345",
      name:"Contoso Gamehelp",
      state:"active",
      placement:"full",
      timestamp:"2012-09-17T07:15:23.4930000",
      activity:
      {
        richPresence:"Nirvana page",
      }
    }]
  }]
}

另请参阅

父级

/users/batch

通过