Skip to main content

POST (/serviceconfigs//batch)

針對服務設定的多個 XBOX 使用者識別碼建立批次查詢。
重要:
此方法由 2015 多人遊戲使用,僅適用於該多人遊戲版本及更新版本。其適用於範本合約 104/105 或更新版本,且每個要求都需要 X-Xbl-Contract-Version: 104/105 或更新版本的標頭元素。

備註

此 HTTP/REST 方法會在服務設定識別碼 (SCID) 層級,針對多個 XBOX 使用者識別碼建立批次查詢。此方法可由 Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetSessionsForUsersFilterAsync 包裝。 對於 2015 多人遊戲,如果所有查詢都相同,只是處理不同的 XBOX 使用者識別碼 (XUID) (如 xuid 查詢字串參數所表示),您可以將許多查詢合併成單一呼叫。請注意,一般查詢和批次查詢的查詢字串參數和回應都相同。 對於批次查詢,屬於每個 XUID 的工作階段會依照 xuid 參數在要求中出現的相同順序寫入回應。同一個工作階段可能會在回應中出現多次,每個符合的 xuid 各出現一次。

URI 參數

| 參數| 類型| 描述| | --- | --- | --- | --- | | scid| GUID| 服務設定識別碼 (SCID)。工作階段識別碼的第 1 部分。|

查詢字串參數

您可以使用下表中的查詢字串參數修改查詢。 | 參數| 類型| 描述| | --- | --- | --- | --- | --- | --- | --- | | keyword| string| 關鍵字,例如 “foo”,工作階段或範本中必須包含此關鍵字才會被擷取。 | | xuid| 64 位元不帶正負號的整數| 要包含在查詢中之工作階段的 XBOX 使用者識別碼,例如 “123”。根據預設,使用者必須在工作階段中處於作用中狀態,該工作階段才會被包含。 | | reservations| boolean| True 表示包含使用者被設為保留玩家但尚未加入成為作用中玩家的工作階段。只有在查詢您自己的工作階段,或以伺服器對伺服器方式查詢特定使用者的工作階段時,才會使用此參數。 | | inactive| boolean| True 表示包含使用者已接受但未在積極遊玩的工作階段。使用者處於 “ready” 但非 “active” 狀態的工作階段會視為非作用中。 | | private| boolean| True 表示包含私人工作階段。只有在查詢您自己的工作階段,或以伺服器對伺服器方式查詢特定使用者的工作階段時,才會使用此參數。 | | visibility| string| 工作階段的可見性狀態。可能的值由 MultiplayerSessionVisibility 定義。如果此參數設為 “open”,查詢應只包含開放的工作階段。如果設為 “private”,則 private 參數必須設為 true。 | | version| 32 位元帶正負號的整數| 應包含的最大工作階段版本。例如,值為 2 表示只應包含主要工作階段版本為 2 或以下的工作階段。版本號碼必須小於或等於要求的合約版本除以 100 的餘數。 | | take| 32 位元帶正負號的整數| 要擷取的工作階段數目上限。此數字必須介於 0 到 100 之間。 | 將 private 或 reservations 設為 true 時,需要具備工作階段的伺服器層級存取權。或者,這些設定需要呼叫者的 XUID 宣告符合 URI 中的 XUID 篩選條件。否則,無論是否確實存在此類工作階段,都會傳回 HTTP/403 狀態碼。

HTTP 狀態碼

服務會傳回適用於 MPSD 的 HTTP 狀態碼。

要求本文

回應本文

此方法的傳回值是工作階段參考的 JSON 陣列,其中內嵌了部分工作階段資料。

另請參閱

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