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

# GDK 中的 HTTP 和 WebSocket 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 文章)](/zh-TW/build/game-principles/security/communication-security-overview) 和 [WinHTTP 概觀](/zh-TW/build/console-features/networking/web-requests/intro-winhttp)，以了解如何確保您的實作安全且穩健。

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

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

若要在 XBOX 上使用以 Proxy 為基礎的偵錯工作流程，請從 [XBOX One 主機上的 Fiddler](/zh-TW/build/console-features/networking/tools/fiddler-setup-networking) 開始。如果您的遊戲使用自訂堆疊，請參閱[偵錯自訂 HTTP 堆疊](/zh-TW/build/console-features/networking/web-requests/debugging-custom-http-stacks)，以取得 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 概觀](/zh-TW/build/console-features/networking/web-requests/intro-xcurl)。

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

<Note>
  `XblHttpCallRequestSet*` 和 `XblHttpCallGet*` 代表用於建置 HTTP 要求和擷取 HTTP 回應的函式群組。

  * [XblHttpCallRequestSetHeader](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetheader)

  * [XblHttpCallRequestSetLongHttpCall](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetlonghttpcall)

  * [XblHttpCallRequestSetRequestBodyBytes](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetrequestbodybytes)

  * [XblHttpCallRequestSetRequestBodyString](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetrequestbodystring)

  * [XblHttpCallRequestSetRetryAllowed](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetretryallowed)

  * [XblHttpCallRequestSetRetryCacheId](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallrequestsetretrycacheid)

  * [XblHttpCallGetHeader](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetheader)

  * [XblHttpCallGetHeaderAtIndex](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetheaderatindex)

  * [XblHttpCallGetNetworkErrorCode](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetnetworkerrorcode)

  * [XblHttpCallGetNumHeaders](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetnumheaders)

  * [XblHttpCallGetPlatformNetworkErrorMessage](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetplatformnetworkerrormessage)

  * [XblHttpCallGetRequestUrl](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetrequesturl)

  * [XblHttpCallGetResponseBodyBytes](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetresponsebodybytes)

  * [XblHttpCallGetResponseBodyBytesSize](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetresponsebodybytessize)

  * [XblHttpCallGetResponseString](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetresponsestring)

  * [XblHttpCallGetStatusCode](/zh-TW/reference/live/xsapi-c/http_call_c/functions/xblhttpcallgetstatuscode)
</Note>

## 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 連線。

如需完整的順序規則及其背後的原因，請參閱[偵測網路初始化狀態](/zh-TW/build/console-features/networking/initialization-connectivity-networking)，以及[回應暫停和繼續](/zh-TW/build/console-features/console-workflows/xbox-game-life-cycle#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 文章)](/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/web-services/live-web-services)

[XBOX One 主機上的 Fiddler](/zh-TW/build/console-features/networking/tools/fiddler-setup-networking)

[通訊安全性概觀 (NDA 文章)](/zh-TW/build/game-principles/security/communication-security-overview)


## Related topics

- [HTTP and WebSocket web requests in the GDK](/build/console-features/networking/web-requests/http-networking.md)
- [HCWebSocketCreate](/zh-CN/reference/live/httpclient/httpclient/functions/hcwebsocketcreate.md)
- [WebSocketCompletionResult](/zh-CN/reference/live/httpclient/httpclient/structs/websocketcompletionresult.md)
- [HCWebSocketConnectAsync](/zh-CN/reference/live/httpclient/httpclient/functions/hcwebsocketconnectasync.md)
- [HCWebSocketGetNumHeaders](/zh-CN/reference/live/httpclient/httpprovider/functions/hcwebsocketgetnumheaders.md)