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

# 設定 API Gateway APIs的 AWS X-Ray 抽樣規則
<a name="apigateway-configuring-xray-sampling-rules"></a>

您可以使用 AWS X-Ray 主控台或 SDK 來設定 Amazon API Gateway API 的抽樣規則。取樣規則指定 X-Ray 應該為您的 API 記錄哪些請求。透過自訂取樣規則，您可以控制記錄的資料量，以及迅速修改取樣行為，而無需修改或重新部署程式碼。

指定您的 X-Ray 取樣規則之前，請先參閱《X-Ray 開發人員指南》中的下列主題：
+ [設定取樣規則](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling)
+ [使用取樣規則搭配 X-Ray API](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-sampling)

**Topics**
+ [API Gateway API 的 X-Ray 取樣規則選項值](#apigateway-xray-sampling-rule-options)
+ [X-Ray 取樣規則範例](#apigateway-xray-sampling-rules-examples)

## API Gateway API 的 X-Ray 取樣規則選項值
<a name="apigateway-xray-sampling-rule-options"></a>

以下 X-Ra 取樣選項與 API Gateway 相關。字串值可以使用萬用字元來以符合單一字元 (?) 或零或多個字元 (\*)。如需詳細資訊，包括如何使用**儲槽**和**比率**設定的詳細說明，請[設定取樣規則](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling)。
+ **Rule name (規則名稱)** (字串) — 規則的唯一名稱。
+ **Priority (優先順序)** (介於 1 和 9999 之間的整數) — 取樣規則的優先順序。服務會以遞增的優先順序來評估規則，並使用符合的第一個規則來決定取樣決策。
+ **Reservoir (儲槽)** (非負整數) — 在套用固定頻率前，每秒檢測的符合請求固定數量。服務不會直接使用蓄水池，而是集體套用至使用該規則的所有服務。
+ **Rate (比率)** (介於 0 到 100 之間的數字) — 在儲槽用盡之後，要檢測的相符請求百分比。
+ **Service name (服務名稱)** (字串) — API 階段名稱，格式為 **{{{api-name}}}/{{{stage-name}}}**。例如，如果您準備將 [PetStore](api-gateway-create-api-from-example.md) 範例 API 部署到名為 `test` 的階段，則在您的取樣規則中應該指定的 **Service name (服務名稱)** 值是 **pets/test**。
+ **Service type (服務類型)** (字串) — 對於 API Gateway API，可指定 **AWS::ApiGateway::Stage** 或 **AWS::ApiGateway::\***。
+ **Host (主機)** (字串) — 來自 HTTP 主機標頭的主機名稱。將此值設定為 **\*** 可符合所有主機名稱。或者，您也可以指定符合全部或部分主機名稱，例如 **api.example.com** 或 **\*.example.com**。
+ **Resource ARN (資源 ARN)** (字串) — API 階段的 ARN，格式為 ，例如 **arn:aws:apigateway:{{region}}::/restapis/{{api-id}}/stages/{{stage-name}}**。

  您可以從主控台或 API Gateway CLI 或 API 取得階段名稱。如需 ARN 格式的詳細資訊，請參閱[Amazon Web Services 一般參考](https://docs.aws.amazon.com/general/latest/gr/)。
+ **HTTP method (HTTP 方法)** (字串) — 取樣的方法，例如 **GET**。
+ **URL path** (URL 路徑) (字串) — 請求的 URL 路徑。
+ (選用) **Attributes (屬性)** (鍵和值) — 來自原始 HTTP 請求的標頭，例如 **Connection**、**Content-Length** 或 **Content-Type**。每個屬性值的長度最多為 32 個字元。

## X-Ray 取樣規則範例
<a name="apigateway-xray-sampling-rules-examples"></a>

**取樣規則範例 \#1**

此規則會取樣 `GET` API 在 `testxray` 階段的所有 `test` 請求。
+ **規則名稱 — ****test-sampling**
+ **優先順序 — ****17**
+ **儲槽大小 — ****10**
+ **固定頻率 — ****10**
+ **服務名稱 — ****testxray/test**
+ **服務類型 — ****AWS::ApiGateway::Stage**
+ **HTTP 方法 — ****GET**
+ **資源 ARN — ****\***
+ **主機 — ****\***

**取樣規則範例 \#2**

此規則會取樣 `testxray` API 在 `prod` 階段的所有請求。
+ **規則名稱 — ****prod-sampling**
+ **優先順序 — ****478**
+ **儲槽大小 — ****1**
+ **固定頻率 — ****60**
+ **服務名稱 — ****testxray/prod**
+ **服務類型 — ****AWS::ApiGateway::Stage**
+ **HTTP 方法 — ****\***
+ **資源 ARN — ****\***
+ **主機 — ****\***
+ **屬性** — **{}**