> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 呼叫 XBOX 服務的最佳做法

> 使用 XSAPI 或 REST 呼叫 XBOX Live 服務的指引，涵蓋等冪與非等冪端點，以及針對網路失敗的適當重試邏輯。

呼叫 XBOX 服務有兩種主要方式：使用 XBOX 服務 API (XSAPI)，或直接呼叫 REST 端點。
無論您的程式碼如何呼叫 XBOX 服務，擁有適當的呼叫模式和重試邏輯都很重要。

若要了解如何撰寫適當的重試邏輯，就必須了解兩種類型的 REST 端點：**等冪**和**非等冪**。
下文將說明這兩種類型。

## 非等冪端點

重複呼叫時會產生副作用的 HTTP 方法被視為**非等冪**。
這表示如果用戶端呼叫端點時發生網路逾時，重試該方法並不安全，因為資源可能已經更新，但網路無法通知呼叫端已成功。

發生錯誤時，用戶端必須先查詢呼叫是否成功，而不是直接重試。
只有在呼叫不成功時，才應該重試。

在 XBOX 服務 API 中，有些 API 在內部標記為呼叫非等冪端點。
這表示如果呼叫這些端點時發生失敗，API 不會自動重試端點。

非等冪 API 的完整清單如下：

* [XblMatchmakingCreateMatchTicketAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/matchmaking_c/functions/xblmatchmakingcreatematchticketasync.md)

* [XblMultiplayerWriteSessionAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionasync.md)

* [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md)

* [XblMultiplayerSendInvitesAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersendinvitesasync.md)

* [XblSocialSubmitReputationFeedbackAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_c/functions/xblsocialsubmitreputationfeedbackasync.md)

* [XblSocialSubmitBatchReputationFeedbackAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/social_c/functions/xblsocialsubmitbatchreputationfeedbackasync.md)

## 等冪方法

另一方面，**等冪** 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](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingssethttpretrydelay.md) 控制的。
這表示根據預設，每次重試都會執行 2、4 或 8 秒以上的指數輪詢。它會根據回應時間，在目前和下一個輪詢值之間抖動延遲，以進一步分散嘗試重試之裝置組的負載。

遊戲應該控制重試呼叫所要花費的時間。
使用 XSAPI 時，開發人員可以使用函式 [XblContextSettingsSetHttpTimeoutWindow](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingssethttptimeoutwindow.md) 直接控制此時間。
根據預設，此值設定為 20 秒。
將此值設定為 0 秒會有效地關閉重試邏輯。

### 動態調整內部 HTTP 逾時

XSAPI 會根據 [XblContextSettingsGetHttpTimeoutWindow](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow.md) 中剩餘的時間，動態調整內部 HTTP 逾時。

內部 HTTP 逾時控制作業系統在中止之前執行 HTTP 網路作業所花費的時間。

除非 [XblContextSettingsGetHttpTimeoutWindow](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow.md) 中至少還剩下 5 秒，讓呼叫有足夠合理的時間完成，否則不會重試呼叫。
此規則不適用於第一次呼叫，因此將 [XblContextSettingsSetHttpTimeoutWindow](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingssethttptimeoutwindow.md) 設定為 0 是可接受的，並會產生單一呼叫。

此邏輯的效果是讓 [XblContextSettingsGetHttpTimeoutWindow](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow.md) 在 API 呼叫何時傳回方面更具確定性。

如果傳回了 "Retry-After" 標頭，則在到達 "Retry-After" 時間之前不會進行任何重試。
如果 "Retry-After" 時間在 [XblContextSettingsGetHttpTimeoutWindow](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow.md) 之後，則呼叫會在 [XblContextSettingsGetHttpTimeoutWindow](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow.md) 結束時傳回。

## 錯誤處理

遊戲開發人員應該**一律**對**每個**服務呼叫使用適當的錯誤處理，他們需要確保正確地處理失敗的回應。

有許多現實情況可能會導致對 XBOX 服務的要求傳回失敗碼，例如：

* 網路無法使用。例如，裝置失去 4G、失去 Wi-Fi，或網路中斷。
* 服務負載過高 (503)。
* 服務上發生失敗 (500)。
* 傳送至服務的要求過多 (429)。
* 寫入作業衝突 (412)。例如，多人遊戲工作階段中的另一位玩家先提交了變更。
* 使用者已遭封鎖或沒有權限。
* 使用者已登出。

適當的錯誤處理常式對於確保遊戲在這些情況下正確運作至關重要。

如需錯誤處理最佳做法的詳細資料，請參閱[錯誤處理](https://learn.microsoft.com/gaming/gdk/docs/services/archive/services-archive/live-error-handling-nav)。

如需涵蓋此主題的影片，請參閱 [Xfest 2015 影片](https://aka.ms/xgddl)中名為 *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，因為社交管理員會在記憶體中維護來自服務之最新資訊的快取。

請參閱[社交管理員](https://docs.xbox.com/zh-TW/services/xbox-services/community/social-manager/live-social-manager-nav.md)。

### 多人遊戲管理員

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

請參閱[多人遊戲管理員](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-nav.md)。

## 節流 (精細速率限制)

XBOX 服務設有節流機制，以防止任何單一裝置對服務造成極端負載。
了解您的遊戲何時遭到節流非常重要。

若要判斷您的遊戲是否遭到節流，請使用下列任一方法：

* 監視 HTTP 狀態碼 429
* 使用偵錯判斷提示
* 使用 XBOX 服務 Trace Analyzer 工具

下文將說明這些方法。

### 監視 HTTP 狀態碼 429

您可以使用 Fiddler 並觀察是否傳回 HTTP 狀態碼 429。
JSON 回應會包含端點如何遭到節流的詳細資料。

例如：

```json theme={null}
{
  "version":1,
  "currentRequests":13,
  "maxRequests":10,
  "periodInSeconds":120,
  "limitType":"Rate"
}
```

如果您使用的是 XSAPI，API 會傳回 **HTTP\_E\_STATUS\_429\_TOO\_MANY\_REQUESTS** 錯誤，並設定錯誤訊息以顯示 API 如何遭到節流的詳細資料。

### 使用偵錯判斷提示

使用 XSAPI 時，如果在開發人員沙箱中使用遊戲的偵錯組建時呼叫遭到節流，它會引發判斷提示，讓開發人員立即知道發生了節流。
這是為了避免因程式碼撰寫不正確而意外遺漏 429 節流錯誤。
如果您想要停用這些判斷提示，以便在不修正違規程式碼的情況下繼續工作，可以使用 [XblDisableAssertsForXboxLiveThrottlingInDevSandboxes](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_global_c/functions/xbldisableassertsforxboxlivethrottlingindevsandboxes.md) API：

```cpp theme={null}
XblDisableAssertsForXboxLiveThrottlingInDevSandboxes(
    XblConfigSetting::ThisCodeNeedsToBeChanged
);
```

此 API 不會防止您的遊戲遭到節流。此 API 會在使用偵錯組建時，於開發沙箱中停用判斷提示。

### 使用 XBOX 服務 Trace Analyzer 工具

判斷您的遊戲是否遭到節流的另一個選項，是記錄 XBOX 服務呼叫的追蹤，然後使用 [XBOX 服務 Trace Analyzer 工具](https://docs.xbox.com/zh-TW/tools/tools-services/live-trace-analyzer.md)分析該追蹤。

若要記錄追蹤，您可以使用 Fiddler 記錄 .SAZ 檔案，或使用 XSAPI 的內建追蹤記錄。
如需在 XSAPI 中開啟追蹤的詳細資訊，請參閱 XBOX 文章 [XBOX 服務 Trace Analyzer (XblTraceAnalyzer.exe)](https://docs.xbox.com/zh-TW/tools/tools-services/live-trace-analyzer.md)。
取得追蹤之後，XBOX 服務 Trace Analyzer 工具會在偵測到遭到節流的呼叫時向您發出警告。

## XBOX 服務是否正常運作？

XBOX 服務是公開 XBOX 功能 (例如個人檔案、好友和線上狀態、統計資料、排行榜、成就、多人遊戲和配對) 之微服務的集合。
沒有任何單一伺服器或端點可以定義 XBOX 服務是否正常運作。
如果單一伺服器停止運作，XBOX 服務的其餘微服務大多是獨立的，應該仍可運作。

如果單一服務遇到暫時中斷，了解此服務呼叫對您的遊戲是否至關重要就很重要。
請嘗試在發生間歇性網路或服務問題時提供合理的體驗。
例如，如果線上狀態服務傳回失敗，該呼叫對您的遊戲而言可能並非至關重要。
請向使用者回報最後已知的線上狀態，而不是回報 XBOX 網路已停止運作。

XBOX 服務遵循「最終一致性」的一致性模型。
這表示如果沒有進行新的更新，最終對該資源的所有要求都會回報最後更新的值。
這表示在資料傳播期間，會有一段短暫的時間資訊是過時的。


## Related topics

- [最佳做法](https://docs.xbox.com/zh-TW/services/xbox-services/develop/best-practices/index.md)
- [精細速率限制](https://docs.xbox.com/zh-TW/services/xbox-services/develop/best-practices/live-fine-grained-rate-limiting.md)
- [RTA 服務的最佳做法](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/rta/concepts/live-rta-best-practices.md)
- [處理離線遊戲的最佳做法](https://docs.xbox.com/zh-TW/services/xbox-services/develop/best-practices/live-best-practices-offline-play.md)
- [即時活動 (RTA) 服務概念 (內容)](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/rta/concepts/live-rta-concepts-nav.md)