> ## 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.

# 取得活動批次

> 取得活動批次

# 取得活動批次

取得使用者清單的一批多人遊戲活動。

此 API 可讓用戶端和服務取得使用者清單的一批活動。

此 API 可能會傳回部分結果；任何指定的使用者都會有完整的活動集，但某些使用者可能完全沒有活動。如果找到部分使用者的活動，就會傳回這些活動。對於找不到活動的使用者，會為該使用者傳回空白清單。對於因內部錯誤而無法擷取活動的使用者，會為該使用者傳回 null；用戶端應重試呼叫。簡而言之，使用者可能有活動清單、空白清單或 null。

```http theme={null}
POST /titles/{titleId}/activities/query
```

## URI 參數

| 參數 | 位置 | 必要 | 類型 | 描述 |
| - | - | - | - | - |
| titleId | path | TRUE | integer | 傳送要求的目標遊戲 titleId。 |

## 要求本文

| 名稱 | 必要 | 類型 | 描述 |
| - | - | - | - |
| users | TRUE | string\[] | 需要擷取其活動資訊之使用者的識別碼。最多支援 30 位使用者。 |

## 要求標頭

| 名稱 | 必要 | 類型 | 描述 |
| - | - | - | - |
| Authorization | TRUE | integer | 呼叫者必須以 XBL 3.0 授權格式提供 XToken。例如，Authorization: XBL3.0 x=2553948354698;>encrypted token \<) |
| Content-Type | TRUE | string | ContentType 必須設定為 application/json |

## 回應

| 名稱 | 類型 | 描述 |
| - | - | - |
| 200 OK | [GetActivityBatchResponse](#getactivitybatchresponse) | 傳回物件包含每位使用者的活動清單。如果使用者沒有目前的活動，該使用者的活動清單將會是空的。如果取得使用者活動時發生服務問題，該使用者的活動清單將會是 null。 |
| 400 Bad Request | [ErrorResponse](#errorresponse) | 處理要求時發生錯誤。可能的錯誤碼："InvalidRequest - The request payload is invalid.", " AuthorizationError: The caller is not allowed to access the resource." |
| 其他狀態碼 | [ThrottledEntity](#throttledentity) | 要求過多。標頭 Retry-After: integer |

## 定義

* [ErrorResponse](#errorresponse)
* [GetActivityBatchRequest](#getactivitybatchrequest)
* [GetActivityBatchResponse](#getactivitybatchresponse)
* [GetActivityResponse](#getactivityresponse)
* [JoinRestriction](#joinrestriction)
* [Platform](#platform)
* [ThrottledEntity](#throttledentity)
* [UserActivity](#useractivity)

### ErrorResponse

| 名稱 | 類型 | 描述 |
| - | - | - |
| debugMessage | string | 可用於偵錯的人類可讀錯誤訊息版本。 |
| errorCode | string | 錯誤碼列舉。 |

### GetActivityBatchRequest

| 名稱 | 類型 | 描述 |
| - | - | - |
| users | string\[] | 需要擷取其活動資訊之使用者的識別碼。最多支援 30 位使用者。 |

### GetActivityBatchResponse

| 名稱 | 類型 | 描述 |
| - | - | - |
| userActivities | [UserActivity](#useractivity)\[] | |

### GetActivityResponse

| 名稱 | 類型 | 描述 |
| - | - | - |
| connectionString | string | 連線字串是傳遞給連線用戶端以加入遊戲的物件。連線字串通常包含伺服器 IP 等資訊，讓加入的使用者能夠連線。連線字串的長度限制為 512 個字元。 |
| currentPlayers | integer | 已在多人遊戲活動中與使用者一起遊玩的玩家人數。 |
| groupId | string | 用來將參與同一場遊戲的所有使用者分組的唯一識別碼。 |
| joinRestriction | [JoinRestriction](#joinrestriction) | 決定誰可以加入目前玩家的設定。 |
| maxPlayers | integer | 在目前活動中可與此玩家一起遊玩的最大玩家人數。 |
| platform | [Platform](#platform) | |
| sequenceNumber | string | 這是單調遞增數字 (ulong) 的字串表示法，用戶端必須在每個要求中傳入。它用於保證活動更新的順序。用戶端的 Unix 時間是 sequenceNumber 的一個好例子，因為它保證會遞增。必須大於 0，且不能大於 ulong 的最大值。 |
| titleId | integer | 要求活動之遊戲的 titleId。 |

### JoinRestriction

| 名稱 | 類型 | 描述 |
| - | - | - |
| Followed | string | |
| InviteOnly | string | |
| Public | string | |

### Platform

| 名稱 | 類型 | 描述 |
| - | - | - |
| Android | string | |
| IOS | string | |
| Nintendo | string | |
| PlayStation | string | |
| Scarlett | string | |
| Win32 | string | |
| WindowsOneCore | string | |
| XboxOne | string | |

### ThrottledEntity

| 名稱 | 類型 | 描述 |
| - | - | - |
| currentRequests | string | 目前的要求數 - 並行或速率。 |
| debugMessage | string | 可用於偵錯的人類可讀節流訊息版本。 |
| limitType | string | 限制類型，即並行或速率。 |
| maxRequests | string | 允許的最大要求數 - 並行或速率。 |
| periodInSeconds | string | 超過速率或並行限制時套用的期間 (以秒為單位)。 |
| version | string | 目前的節流合約版本。 |

### UserActivity

| 名稱 | 類型 | 描述 |
| - | - | - |
| activities | [GetActivityResponse](#getactivityresponse)\[] | |
| userId | string | |


## Related topics

- [多人遊戲活動的範例程式碼](/zh-TW/services/xbox-services/multiplayer/mpa/how-to/live-mpa-client-how-to.md)
- [XblMultiplayerActivityGetActivityResult](/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityresult.md)
- [XblMultiplayerActivityInfo](/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/structs/xblmultiplayeractivityinfo.md)
- [XblMultiplayerActivityGetActivityResultSize](/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityresultsize.md)
- [XblMultiplayerActivityGetActivityAsync](/zh-TW/reference/live/xsapi-c/multiplayer_activity_c/functions/xblmultiplayeractivitygetactivityasync.md)