# 为 API Gateway API 配置 Amazon X-Ray 采样规则
<a name="apigateway-configuring-xray-sampling-rules"></a>

您可以使用 Amazon X-Ray 控制台或开发工具包为您的 Amazon API Gateway API 配置采样规则。采样规则指定了 X-Ray 应为您的 API 记录哪些请求。通过自定义采样规则，您可以控制您记录的数据量，并即刻修改采样行为，而不修改或重新部署您的代码。

指定您的 X-Ray 采样规则之前，请阅读《X-Ray 开发人员指南》中的以下主题：
+ [配置采样规则](https://docs.amazonaws.cn/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling)
+ [通过 X-Ray API 使用采样规则](https://docs.amazonaws.cn/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-Ray 采样选项与 API Gateway 相关。字符串值可以使用通配符来匹配单个字符 (?) 或零或多个字符 (\$1)。有关更多详细信息，包括如何使用**容器**和**速率**设置的详细说明，请参阅[配置采样规则](https://docs.amazonaws.cn/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling)。
+ **规则名称**（字符串）— 一个唯一的规则名称。
+ **优先级**（1 和 9999 之间的整数）— 采样规则的优先级。服务按优先级的上升顺序评估规则，并与匹配的第一条规则进行抽样决策。
+ **容器**（非负整数）— 在应用固定速率之前，每秒要分析的匹配请求的固定数量。该容器不由服务直接使用，但适用于所有使用该规则的服务。
+ **速率**（0 到 100 之间的数字）— 容器耗尽后，要分析的匹配请求的百分比。
+ **服务名称**（字符串）— API 阶段名称，形式为 ***\$1api-name\$1*/*\$1stage-name\$1***。例如，如果您要将 [PetStore](api-gateway-create-api-from-example.md) 示例 API 部署到名为 `test` 的阶段，则要在您的采样规则中指定的 **Service name (服务名称)** 值应为 **pets/test**。
+ **服务类型**（字符串）— 对于 API Gateway API，可以指定 **AWS::ApiGateway::Stage** 或 **AWS::ApiGateway::\$1**。
+ **主机**（字符串）— HTTP 主机标头中的主机名。请将 **\$1** 设置为匹配所有的主机名。或者，您可以指定完整的或部分主机名进行匹配，例如 **api.example.com** 或 **\$1.example.com**。
+ **资源 ARN**（字符串）– API 阶段的 ARN，例如 **arn:aws:apigateway:*region*::/restapis/*api-id*/stages/*stage-name***。

  该阶段名可以从控制台或 API Gateway CLI 或 API 获取。有关 ARN 格式的更多信息，请参阅 [Amazon Web Services 一般参考](https://docs.amazonaws.cn/general/latest/gr/)。
+ **HTTP 方法**（字符串）— 要采样的方法，例如 **GET**。
+ **URL path (URL 路径)**（字符串） — 请求的 URL 路径。
+ （可选）**属性**（密钥和值）— 来自原始 HTTP 请求的标头，例如 **Connection**、**Content-Length** 或 **Content-Type**。每个属性值的长度最多为 32 个字符。

## X-Ray 采样规则示例
<a name="apigateway-xray-sampling-rules-examples"></a>

**采样规则示例 \$11**

此规则在 `GET` 阶段针对 `testxray` API 所有的 `test` 请求采样。
+ **规则名称 — ****test-sampling**
+ **优先级 - ****17**
+ **容器大小 - ****10**
+ **固定速率 - ****10**
+ **服务名称 - ****testxray/test**
+ **服务类型 - ****AWS::ApiGateway::Stage**
+ **HTTP 方法 - ****GET**
+ **资源 ARN - ****\$1**
+ **主机 — ****\$1**

**采样规则示例 \$12**

此规则在 `testxray` 阶段针对 `prod` API 的所有请求采样。
+ **规则名称 — ****prod-sampling**
+ **优先级 - ****478**
+ **容器大小 - ****1**
+ **固定速率 - ****60**
+ **服务名称 - ****testxray/prod**
+ **服务类型 - ****AWS::ApiGateway::Stage**
+ **HTTP 方法 - ****\$1**
+ **资源 ARN - ****\$1**
+ **主机 — ****\$1**
+ **属性** — **\$1\$1**