> ## 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 使用者識別碼 (XUID) | 403 Forbidden |
## 隱私權設定對資源的影響
此方法一律會傳回 200 OK，但回應本文中可能不會傳回內容。
\| 提出要求的使用者| 目標使用者的隱私權設定| 行為|
\| --- | --- | --- | --- | --- | --- | --- |
\| 我| -| 200 OK|
\| 朋友| 所有人| 200 OK|
\| 朋友| 僅限朋友| 200 OK|
\| 朋友| 已封鎖| 200 OK|
\| 非朋友使用者| 所有人| 200 OK|
\| 非朋友使用者| 僅限朋友| 200 OK|
\| 非朋友使用者| 已封鎖| 200 OK|
\| 協力廠商網站| 所有人| 200 OK|
\| 協力廠商網站| 僅限朋友| 200 OK|
\| 協力廠商網站| 已封鎖| 200 OK|
## 必要的要求標頭
\| 標頭| 類型| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| Authorization| string| HTTP 驗證的驗證認證。範例值："XBL3.0 x=\;\"。|
\| x-xbl-contract-version| string| 此要求應導向之 XBOX LIVE 服務的組建名稱/編號。只有在驗證標頭的有效性、驗證權杖中的宣告等之後，要求才會路由至該服務。範例值：3、vnext。|
\| Accept| string| 可接受的 Content-Type。Presence 唯一支援的是 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，批次作業將篩選掉離線使用者 (包括隱身使用者) 的記錄。如果未提供此屬性，則會同時傳回線上和離線使用者。|
### 禁止的成員
要求中禁止使用所有其他成員。
### 要求範例
```cpp theme={null}
{
users:
[
"1234567890",
"4567890123",
"7890123456"
]
}
```
## 回應本文
### 回應範例
此方法會傳回 [PresenceRecord](/zh-TW/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](/zh-TW/reference/live/rest/uri/presence/uri-usersbatch)
## Related topics
- [XblSocialSubmitBatchReputationFeedbackAsync](/zh-CN/reference/live/xsapi-c/social_c/functions/xblsocialsubmitbatchreputationfeedbackasync.md)
- [XblUserStatisticsGetMultipleUserStatisticsAsync](/ko/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsgetmultipleuserstatisticsasync.md)