本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 的 Amazon API Gateway 主動追蹤支援 AWS X-Ray
<a name="xray-services-apigateway"></a>

您可以使用 X-Ray 在使用者請求通過 Amazon API Gateway APIs 到基礎服務時追蹤和分析使用者請求。API Gateway 支援所有 API Gateway 端點類型的 X-Ray 追蹤：區域、邊緣最佳化和私有。您可以在可使用 X-Ray 的所有 AWS 區域 中使用 X-Ray 搭配 Amazon API Gateway。如需詳細資訊，請參閱《Amazon API Gateway [API Gateway 開發人員指南》中的使用 追蹤 API Gateway API 執行 AWS X-Ray](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html)。

**注意**  
X-Ray 僅支援透過 APIs Gateway 追蹤 REST API。

Amazon API Gateway 提供 的[主動追蹤](xray-services.md)支援 AWS X-Ray。在您的 API 階段上啟用主動追蹤，以取樣傳入的請求，並將追蹤傳送至 X-Ray。

**啟用 API 階段的主動追蹤**

1. 在以下網址開啟 API Gateway 主控台：[https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/)。

1. 選擇一個 API。

1. 選擇一個階段。

1. 在**日誌/追蹤**索引標籤上，選擇**啟用 X-Ray 追蹤**，然後選擇**儲存變更**。

1. 在左側導覽窗格中，選擇 **Resources (資源)**。

1. 若要使用新設定重新部署 API，請選擇**動作**下拉式清單，然後選擇**部署 API**。

API Gateway 會使用您在 X-Ray 主控台中定義的抽樣規則來決定要記錄哪些請求。您可以建立僅適用於 APIs規則，或僅適用於包含特定標頭的請求的規則。API Gateway 會在區段的屬性中記錄標頭，以及階段和請求的詳細資訊。如需詳細資訊，請參閱[設定 取樣規則](xray-console-sampling.md)。

**注意**  
使用 API Gateway [HTTP 整合](https://docs.aws.amazon.com/apigateway/latest/developerguide/setup-http-integrations.html)追蹤 REST APIs 時，每個區段的服務名稱會設定為從 API Gateway 到 HTTP 整合端點的請求 URL 路徑，導致每個唯一 URL 路徑的 X-Ray 追蹤映射上有一個服務節點。大量的 URL 路徑可能會導致追蹤映射超過 10，000 個節點的限制，進而導致錯誤。  
若要將 API Gateway 建立的服務節點數量降至最低，請考慮在 URL 查詢字串內或透過 POST 在請求內文中傳遞參數。這兩種方法都會確保參數不屬於 URL 路徑，這可能會導致不同的 URL 路徑和服務節點較少。

對於所有傳入請求，API Gateway 會將[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)新增至尚未有的傳入 HTTP 請求。

```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793
```

**X-Ray 追蹤 ID 格式**

X-Ray `trace_id`由以連字號分隔的三個數字組成。例如：`1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。

  例如，太平洋標準時間 2016 年 12 月 1 日上午 10：00，以秒`1480615200`為單位或以十六進位數字`58406520`為單位。
+ 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字**表示。

即使停用主動追蹤，如果請求是來自已抽樣請求並已開始追蹤的服務，階段仍會記錄區段。例如，經檢測的 Web 應用程式可以使用 HTTP 用戶端呼叫 API Gateway API。當您使用 X-Ray SDK 檢測 HTTP 用戶端時，它會將追蹤標頭新增至包含抽樣決策的傳出請求。API Gateway 會讀取追蹤標頭，並為取樣的請求建立區段。

如果您使用 API Gateway [為您的 API 產生 Java SDK](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-generate-sdk.html)，您可以透過使用用戶端建置器新增請求處理常式來檢測 SDK 用戶端，方法與手動檢測 AWS SDK 用戶端的方式相同。如需說明，請參閱 [使用適用於 Java 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-java-awssdkclients.md)。