> ## 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 (/users/batch)

> POST (/users/batch)

# POST (/users/batch)

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

* [备注](#ID4EV)
* [授权](#ID4EAB)
* [隐私设置对资源的影响](#ID4EDC)
* [必需的请求标头](#ID4EYF)
* [可选的请求标头](#ID4EGAAC)
* [请求正文](#ID4EGBAC)
* [响应正文](#ID4ESEAC)

## 备注

任何希望了解一批用户在线状态信息的客户端、服务或标题都应使用此方法。

此批处理请求的响应可按深度和路径进行筛选。使用者可以借此查询并显示一组用户的在线状态。此 API 上的筛选器在同一属性内以 OR 方式起作用,而在不同属性之间则以 AND 方式起作用。

## 授权

| 类型 | 是否必需 | 说明 | 缺失时的响应 |
| - | - | - | - |
| XUID | 是 | 调用方的 XBOX 用户 ID (XUID) | 403 Forbidden |

## 隐私设置对资源的影响

此方法始终返回 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 | 可能的值:<ul><li>user - 获取用户节点</li><li>device - 获取用户和设备节点</li><li>title - 获取标题级基本信息</li><li>all - 获取丰富在线状态信息、媒体信息或两者</li></ul>\
默认为 "title"。 |
\| onlineOnly | 如果此属性为 true,则批处理操作将筛选掉离线用户(包括隐身用户)的记录。如果未提供,将同时返回在线和离线用户。 |

### 禁止的成员

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

### 示例请求

```cpp theme={null}
{
  users:
  [
    "1234567890",
    "4567890123",
    "7890123456"
  ]
}

```

## 响应正文

### 示例响应

此方法返回 [PresenceRecord](https://devdocs.xbox.com/zh-CN/reference/live/rest/json/json-presencerecord)。

```cpp theme={null}
{
  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](https://devdocs.xbox.com/zh-CN/reference/live/rest/uri/presence/uri-usersbatch)


## Related topics

- [XblSocialSubmitBatchReputationFeedbackAsync](https://devdocs.xbox.com/fr-CA/reference/live/xsapi-c/social_c/functions/xblsocialsubmitbatchreputationfeedbackasync.md)
- [XblUserStatisticsGetMultipleUserStatisticsAsync](https://devdocs.xbox.com/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsgetmultipleuserstatisticsasync.md)