跳轉到主要內容
呼叫 XBOX 服務有兩種主要方式：使用 XBOX 服務 API (XSAPI)，或直接呼叫 REST 端點。 無論您的程式碼如何呼叫 XBOX 服務，擁有適當的呼叫模式和重試邏輯都很重要。 若要了解如何撰寫適當的重試邏輯，就必須了解兩種類型的 REST 端點：等冪和非等冪。 下文將說明這兩種類型。

​
非等冪端點

重複呼叫時會產生副作用的 HTTP 方法被視為非等冪。 這表示如果用戶端呼叫端點時發生網路逾時，重試該方法並不安全，因為資源可能已經更新，但網路無法通知呼叫端已成功。 發生錯誤時，用戶端必須先查詢呼叫是否成功，而不是直接重試。 只有在呼叫不成功時，才應該重試。 在 XBOX 服務 API 中，有些 API 在內部標記為呼叫非等冪端點。 這表示如果呼叫這些端點時發生失敗，API 不會自動重試端點。 非等冪 API 的完整清單如下：

​
等冪方法

另一方面，等冪 HTTP 方法不會留下副作用。 這也表示重試它們是安全的。 在 XBOX 服務 API 中，所有等冪方法都會在特定條件下自動重試。 等冪 API 的完整清單是上述未列為非等冪的所有 API。

​
重試邏輯最佳做法

對於等冪呼叫，下列條件應該自動重試：
  • 所有網路錯誤
  • 401: Unauthorized
  • 408: RequestTimeout
  • 429: Too Many Requests
  • 500: InternalError
  • 502: BadGateway
  • 503: ServiceUnavailable
  • 504: GatewayTimeout
在 UWP 上，401: Unauthorized 會受到特殊處理。 此值表示 XBOX 服務驗證權杖已到期，因此 XBOX 服務 API 會呼叫作業系統以重新整理權杖，然後執行一次重試。 執行重試時，最佳做法是在到達 “Retry-After” 標頭時間之前不要呼叫服務。 XSAPI 現在已實作此最佳做法。 如果任何 API 傳回失敗的 HTTP 狀態碼和 “Retry-After” 標頭，則在 Retry-After 時間之前對同一個 API 的其他呼叫，會立即傳回原始錯誤，而不會連線至服務。 重試呼叫時，最佳做法是執行帶有隨機抖動的指數輪詢，以分散服務的負載。 XSAPI 從預設延遲 2 秒開始，此延遲是使用 XblContextSettingsSetHttpRetryDelay 控制的。 這表示根據預設，每次重試都會執行 2、4 或 8 秒以上的指數輪詢。它會根據回應時間，在目前和下一個輪詢值之間抖動延遲，以進一步分散嘗試重試之裝置組的負載。 遊戲應該控制重試呼叫所要花費的時間。 使用 XSAPI 時，開發人員可以使用函式 XblContextSettingsSetHttpTimeoutWindow 直接控制此時間。 根據預設，此值設定為 20 秒。 將此值設定為 0 秒會有效地關閉重試邏輯。

​
動態調整內部 HTTP 逾時

XSAPI 會根據 XblContextSettingsGetHttpTimeoutWindow 中剩餘的時間，動態調整內部 HTTP 逾時。 內部 HTTP 逾時控制作業系統在中止之前執行 HTTP 網路作業所花費的時間。 除非 XblContextSettingsGetHttpTimeoutWindow 中至少還剩下 5 秒，讓呼叫有足夠合理的時間完成，否則不會重試呼叫。 此規則不適用於第一次呼叫，因此將 XblContextSettingsSetHttpTimeoutWindow 設定為 0 是可接受的，並會產生單一呼叫。 此邏輯的效果是讓 XblContextSettingsGetHttpTimeoutWindow 在 API 呼叫何時傳回方面更具確定性。 如果傳回了 “Retry-After” 標頭，則在到達 “Retry-After” 時間之前不會進行任何重試。 如果 “Retry-After” 時間在 XblContextSettingsGetHttpTimeoutWindow 之後，則呼叫會在 XblContextSettingsGetHttpTimeoutWindow 結束時傳回。

​
錯誤處理

遊戲開發人員應該一律對每個服務呼叫使用適當的錯誤處理，他們需要確保正確地處理失敗的回應。 有許多現實情況可能會導致對 XBOX 服務的要求傳回失敗碼，例如：
  • 網路無法使用。例如，裝置失去 4G、失去 Wi-Fi，或網路中斷。
  • 服務負載過高 (503)。
  • 服務上發生失敗 (500)。
  • 傳送至服務的要求過多 (429)。
  • 寫入作業衝突 (412)。例如，多人遊戲工作階段中的另一位玩家先提交了變更。
  • 使用者已遭封鎖或沒有權限。
  • 使用者已登出。
適當的錯誤處理常式對於確保遊戲在這些情況下正確運作至關重要。 如需錯誤處理最佳做法的詳細資料，請參閱錯誤處理。 如需涵蓋此主題的影片，請參閱 Xfest 2015 影片中名為 XSAPI: C++, No Exceptions! 的演講。

​
最佳呼叫模式

​
使用批次處理要求

有些端點支援將一組要求批次處理或彙總成單一呼叫。 例如，使用 XBOX 服務的個人檔案服務，您可以要求單一使用者的個人檔案，或一組使用者的個人檔案。 因此，如果您需要一組使用者的個人檔案，針對每個使用者個人檔案逐一呼叫端點或 API 會非常沒有效率。 每次呼叫都會增加大量的驗證負擔。 因此，請改為一次將您想要取得資訊的所有使用者傳遞給 API，讓端點可以同時處理所有使用者個人檔案，並傳回單一回應。

​
使用即時活動 (RTA) 服務，而不要輪詢

最佳做法是使用即時活動 (RTA) 服務，而不是定期輪詢。 即時活動服務會公開 Web 通訊端，在服務上的目標資源變更時傳送通知給用戶端。 RTA 服務會針對線上狀態變更、統計資料變更、多人遊戲工作階段文件變更和社交關係變更提供通知。 若要讓用戶端得知其感興趣的資訊，用戶端必須先透過 Web 通訊端訂閱該項目。 這可避免輪詢服務來偵測變更，因為您會在項目變更時確切得知。 XSAPI 將 RTA 服務公開為一組用戶端可以使用的訂閱 API。 這些 API 都有對應的 *ChangedHandler API，它們會接受在項目變更時呼叫的回呼函式。
  • XblPresenceSubscribeToDevicePresenceChange
  • XblPresenceSubscribeToTitlePresenceChange
  • XblUserStatisticsSubscribeToStatisticChange
  • XblSocialSubscribeToSocialRelationshipChange

​
使用 XSAPI 用戶端管理員

XSAPI 有一組管理員，作為快取和狀態機，可為特定案例處理所有繁重的工作。

​
社交管理員

社交管理員會處理好友清單和個人檔案的所有繁重工作。 社交管理員會使用 RTA 服務讓您的好友清單、他們的個人檔案及其線上狀態資料保持最新。 社交管理員公開了對遊戲引擎非常友善的同步 API。 遊戲可以經常呼叫社交管理員 API，因為社交管理員會在記憶體中維護來自服務之最新資訊的快取。 請參閱社交管理員。

​
多人遊戲管理員

對於多人遊戲工作階段管理，多人遊戲管理員是適用於傳統多人遊戲的隨插即用解決方案。 多人遊戲管理員 API 包含玩家名冊和工作階段管理，可處理遊戲邀請、中途加入和配對，並可插入您現有的網路解決方案。 它會處理實作傳統多人遊戲流程的所有繁重工作。 請參閱多人遊戲管理員。

​
節流 (精細速率限制)

XBOX 服務設有節流機制，以防止任何單一裝置對服務造成極端負載。 了解您的遊戲何時遭到節流非常重要。 若要判斷您的遊戲是否遭到節流，請使用下列任一方法：
  • 監視 HTTP 狀態碼 429
  • 使用偵錯判斷提示
  • 使用 XBOX 服務 Trace Analyzer 工具
下文將說明這些方法。

​
監視 HTTP 狀態碼 429

您可以使用 Fiddler 並觀察是否傳回 HTTP 狀態碼 429。 JSON 回應會包含端點如何遭到節流的詳細資料。 例如：
如果您使用的是 XSAPI，API 會傳回 HTTP_E_STATUS_429_TOO_MANY_REQUESTS 錯誤，並設定錯誤訊息以顯示 API 如何遭到節流的詳細資料。

​
使用偵錯判斷提示

使用 XSAPI 時，如果在開發人員沙箱中使用遊戲的偵錯組建時呼叫遭到節流，它會引發判斷提示，讓開發人員立即知道發生了節流。 這是為了避免因程式碼撰寫不正確而意外遺漏 429 節流錯誤。 如果您想要停用這些判斷提示，以便在不修正違規程式碼的情況下繼續工作，可以使用 XblDisableAssertsForXboxLiveThrottlingInDevSandboxes API：
此 API 不會防止您的遊戲遭到節流。此 API 會在使用偵錯組建時，於開發沙箱中停用判斷提示。

​
使用 XBOX 服務 Trace Analyzer 工具

判斷您的遊戲是否遭到節流的另一個選項，是記錄 XBOX 服務呼叫的追蹤，然後使用 XBOX 服務 Trace Analyzer 工具分析該追蹤。 若要記錄追蹤，您可以使用 Fiddler 記錄 .SAZ 檔案，或使用 XSAPI 的內建追蹤記錄。 如需在 XSAPI 中開啟追蹤的詳細資訊，請參閱 XBOX 文章 XBOX 服務 Trace Analyzer (XblTraceAnalyzer.exe)。 取得追蹤之後，XBOX 服務 Trace Analyzer 工具會在偵測到遭到節流的呼叫時向您發出警告。

​
XBOX 服務是否正常運作？

XBOX 服務是公開 XBOX 功能 (例如個人檔案、好友和線上狀態、統計資料、排行榜、成就、多人遊戲和配對) 之微服務的集合。 沒有任何單一伺服器或端點可以定義 XBOX 服務是否正常運作。 如果單一伺服器停止運作，XBOX 服務的其餘微服務大多是獨立的，應該仍可運作。 如果單一服務遇到暫時中斷，了解此服務呼叫對您的遊戲是否至關重要就很重要。 請嘗試在發生間歇性網路或服務問題時提供合理的體驗。 例如，如果線上狀態服務傳回失敗，該呼叫對您的遊戲而言可能並非至關重要。 請向使用者回報最後已知的線上狀態，而不是回報 XBOX 網路已停止運作。 XBOX 服務遵循「最終一致性」的一致性模型。 這表示如果沒有進行新的更新，最終對該資源的所有要求都會回報最後更新的值。 這表示在資料傳播期間，會有一段短暫的時間資訊是過時的。
最後修改於 2026年10月19日