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

# Web 要求概觀

> 為 GDK 遊戲中的 HTTP 和 WebSocket 呼叫選擇 xCurl、libHttpClient 或 WinHTTP，並在主機上正確處理暫停和繼續。

本文概述 Microsoft Game Development Kit (GDK) 遊戲的超文字傳輸通訊協定 (HTTP) 和 WebSocket Web 要求。

從正確的 API 集開始，可讓您更輕鬆地實作安全且穩健的 Web 要求。

## GDK 遊戲的常用 API

下列 API 常用於 Microsoft Game Development Kit (GDK) 遊戲中安全且穩健的 Web 要求。它們也有助於簡化實作。

| 使用案例 | 常用的 API 選擇 |
| - | - |
| 使用 Gaming Runtime Services (GRTS) 樣式 API 的 REST 要求 | [Microsoft XBOX Live Service API (XSAPI)](#xsapi) |
| 一般用途的 HTTP 要求 | [xCurl](#xcurl) |
| WebSocket 要求 | [libHttpClient](#libhttpclient) |

**Windows HTTP 服務 (WinHTTP)**

WinHTTP 也可用來在 PC 和 XBOX 主機上建立 HTTP 和 WebSocket 服務端點，而不需要變更程式碼。由於此 API 不會自動處理所有安全性最佳做法，請務必閱讀[通訊安全性概觀 (NDA 文章)](https://docs.xbox.com/zh-TW/build/game-principles/security/communication-security-overview.md) 和 [WinHTTP 概觀](https://docs.xbox.com/zh-TW/build/console-features/networking/web-requests/intro-winhttp.md)，以了解如何確保您的實作安全且穩健。

`xCurl` 會處理安全性最佳做法，包括憑證鏈結驗證和網路連線檢查。它也會自動管理網路初始化和暫停/繼續。

如果您的遊戲使用 WinHTTP 或其他 HTTP 堆疊而非 xCurl，請假設遊戲需負責平台整合工作，例如網路初始化、暫停/繼續處理及明確的安全性設定。如需順序和生命週期指引，請參閱[網路初始化與連線能力](https://docs.xbox.com/zh-TW/build/console-features/networking/initialization-connectivity-networking.md)和 [WinHTTP 概觀](https://docs.xbox.com/zh-TW/build/console-features/networking/web-requests/intro-winhttp.md)。

若要在 XBOX 上使用以 Proxy 為基礎的偵錯工作流程，請從 [XBOX 主機上的 Fiddler](https://docs.xbox.com/zh-TW/build/console-features/networking/tools/fiddler-setup-networking.md) 開始。如果您的遊戲使用自訂堆疊，請參閱[偵錯自訂 HTTP 堆疊](https://docs.xbox.com/zh-TW/build/console-features/networking/web-requests/debugging-custom-http-stacks.md)，以取得 XBOX 專用的 Proxy 和憑證指引。

## xCurl

**xCurl** 是 Microsoft Game Development Kit (GDK) 遊戲可用的 HTTP API。它會自動遵循所有安全性最佳做法，藉此簡化遊戲開發。由於 API 介面大致與 [libCurl](https://curl.haxx.se/libcurl/) 相符，因此它也具備 libCurl 的完整彈性和 HTTP 功能集。

若要深入了解 **xCurl** API 以及 **xCurl** 與 **libCurl** 之間的差異，請參閱 [xCurl 概觀](https://docs.xbox.com/zh-TW/build/console-features/networking/web-requests/intro-xcurl.md)。

## XSAPI

[XBOX Services API (XSAPI)](https://developer.microsoft.com/games/xbox/docs/gdk/atoc-xsapi-c) 為 Microsoft Game Development Kit (GDK) 遊戲提供通用的 REST 包裝函式。此包裝函式易於使用，並遵循 Microsoft Game Development Kit (GDK) 非同步 API 模型。如果您的遊戲只需要發出 REST HTTP 要求，這可能是最簡單的介面。

1. 使用 [XblHttpCallCreate](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallcreate.md) 建立 HTTP 控制代碼以追蹤您的 `REST` 要求。
2. 使用其中一個 `XblHttpCallRequestSet*` 函式填入本文和任何額外設定。
3. 呼叫 [XblHttpCallPerformAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallperformasync.md) 以發出要求。
4. 若要擷取回應，請使用其中一個 `XblHttpCallGet*` 函式。
5. 使用 [XblHttpCallCloseHandle](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallclosehandle.md) 關閉控制代碼。

> [!NOTE]
>
> `XblHttpCallRequestSet*` 和 `XblHttpCallGet*` 代表用於建置 HTTP 要求和擷取 HTTP 回應的函式群組。
>
> * [XblHttpCallRequestSetHeader](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetheader.md)
>
> * [XblHttpCallRequestSetLongHttpCall](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetlonghttpcall.md)
>
> * [XblHttpCallRequestSetRequestBodyBytes](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetrequestbodybytes.md)
>
> * [XblHttpCallRequestSetRequestBodyString](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetrequestbodystring.md)
>
> * [XblHttpCallRequestSetRetryAllowed](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetretryallowed.md)
>
> * [XblHttpCallRequestSetRetryCacheId](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetretrycacheid.md)
>
> * [XblHttpCallGetHeader](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetheader.md)
>
> * [XblHttpCallGetHeaderAtIndex](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetheaderatindex.md)
>
> * [XblHttpCallGetNetworkErrorCode](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetnetworkerrorcode.md)
>
> * [XblHttpCallGetNumHeaders](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetnumheaders.md)
>
> * [XblHttpCallGetPlatformNetworkErrorMessage](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetplatformnetworkerrormessage.md)
>
> * [XblHttpCallGetRequestUrl](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetrequesturl.md)
>
> * [XblHttpCallGetResponseBodyBytes](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetresponsebodybytes.md)
>
> * [XblHttpCallGetResponseBodyBytesSize](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetresponsebodybytessize.md)
>
> * [XblHttpCallGetResponseString](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetresponsestring.md)
>
> * [XblHttpCallGetStatusCode](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetstatuscode.md)

## libHttpClient

[libHttpClient](https://github.com/Microsoft/libHttpClient) 的設計目的是啟用雙向通訊。它是一個抽象層，專供 XBOX Live Service API (XSAPI) 使用，以啟用 HTTP 和 WebSocket 服務端點。此 API 作為 XSAPI 的一部分包含在 Game Development Kit (GDK) 中。

### 使用 libHttpClient 進行暫停和繼續

與 xCurl 不同，`libHttpClient` 不會在遊戲暫停時自動清空或終止進行中的工作。使用 `libHttpClient` (包括其 WebSocket 支援) 的遊戲必須明確處理暫停/繼續生命週期。零售版主機會在待命時進入暫停狀態，因此即使相同的遊戲在開發套件上能正常暫停和繼續，在暫停期間仍保持開啟的 WebSocket 連線或非同步作業也可能在繼續時停止回應或當機。

在暫停或關機時：

* 停止將新的 HTTP 和 WebSocket 工作排入佇列。
* 取消或清空進行中的要求，以及 WebSocket 傳送和接收。
* 關閉 WebSocket 連線，並終結不應在暫停後保留的 HTTP 呼叫控制代碼、工作階段和通訊端。

在繼續時，請等候 `XNetworkingConnectivityHint::networkInitialized` 為 `true`，再重新建立 `libHttpClient` 狀態或重新開啟 WebSocket 連線。

如需完整的順序規則及其背後的原因，請參閱[偵測網路初始化狀態](https://docs.xbox.com/zh-TW/build/console-features/networking/initialization-connectivity-networking.md)，以及[回應暫停和繼續](https://docs.xbox.com/zh-TW/build/console-features/console-workflows/xbox-game-life-cycle.md#responding-to-suspend-and-resume)中的遊戲生命週期指引。

## 另請參閱

[Windows HTTP 服務 (WinHTTP)](https://learn.microsoft.com/windows/desktop/winhttp/winhttp-start-page)

[libCurl](https://curl.haxx.se/libcurl/)

[在 Partner Center 設定 Web 服務 (NDA 文章)](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/web-services/live-web-services.md)

[XBOX 主機上的 Fiddler](https://docs.xbox.com/zh-TW/build/console-features/networking/tools/fiddler-setup-networking.md)

[通訊安全性概觀 (NDA 文章)](https://docs.xbox.com/zh-TW/build/game-principles/security/communication-security-overview.md)


## Related topics

- [Web 要求](https://docs.xbox.com/zh-TW/build/console-features/networking/web-requests/web-requests-toc.md)
- [要求和管理光碟](https://docs.xbox.com/zh-TW/publishing/game-publishing/how-to/how-to-request-and-manage-discs.md)
- [建立光碟](https://docs.xbox.com/zh-TW/build/core-features/common/packaging/creating-discs.md)
- [xCurl 概觀](https://docs.xbox.com/zh-TW/build/console-features/networking/web-requests/intro-xcurl.md)
- [PlayFab Party 概觀](https://docs.xbox.com/zh-TW/build/console-features/networking/index.md)