Skip to main content

POST (/users/batch)

取得一批使用者的目前狀態。 這些 URI 的網域為 userpresence.xboxlive.com。

備註

任何想要了解一批使用者目前狀態資訊的用戶端、服務或遊戲,都應使用此方法。 此批次要求的回應可以依深度和路徑進行篩選。取用者可以使用此功能來找出並顯示一組使用者的目前狀態。此 API 上的篩選條件在同一屬性內以 OR 運作,但跨屬性則以 AND 運作。

授權

隱私權設定對資源的影響

此方法一律會傳回 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=<userhash>;<token>”。| | 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,批次作業將篩選掉離線使用者 (包括隱身使用者) 的記錄。如果未提供此屬性,則會同時傳回線上和離線使用者。|

禁止的成員

要求中禁止使用所有其他成員。

要求範例

回應本文

回應範例

此方法會傳回 PresenceRecord。

另請參閱

上層
/users/batch
Last modified on October 6, 2026