# 使用 API Gateway REST API 设置 Amazon X-Ray
<a name="apigateway-enabling-xray"></a>

在本节中，您可以找到有关如何使用 API Gateway REST API 设置 [Amazon X-Ray](https://docs.amazonaws.cn/xray/latest/devguide/xray-services-apigateway.html) 的详细信息。

**Topics**
+ [API Gateway 的 X-Ray 跟踪模式](#apigateway-tracing-modes)
+ [X-Ray 跟踪的权限](#set-up-xray-tracing-permissions)
+ [在 API Gateway 控制台中启用 X-Ray 跟踪](#apigateway-xray-console-setup)
+ [使用 API Gateway CLI 启用 Amazon X-Ray 跟踪](#apigateway-xray-cli-setup)

## API Gateway 的 X-Ray 跟踪模式
<a name="apigateway-tracing-modes"></a>

通过跟踪 ID 来跟踪请求在您的应用程序中传输的路径。跟踪会收集单个请求（通常是 HTTP `GET` 或 `POST` 请求）生成的所有分段。

API Gateway API 的跟踪有两种模式：
+ **被动**：如果您尚未在 API 阶段上启用 X-Ray 跟踪，则此模式为默认设置。此方法意味着，只有在上游服务上启用 X-Ray 后才会跟踪 API Gateway API。
+ **主动**：如果 API Gateway API 阶段具有此设置， API Gateway 会自动根据 X-Ray 指定的采样算法对 API 调用请求进行采样。

  在一个阶段上启用主动跟踪时，如果服务相关角色不存在，API Gateway 会在您的账户中创建该角色。该角色被命名为 `AWSServiceRoleForAPIGateway`，且将 `APIGatewayServiceRolePolicy` 托管策略附加于此。有关服务相关角色的更多信息，请参阅[使用服务相关角色](https://docs.amazonaws.cn/IAM/latest/UserGuide/using-service-linked-roles.html)。
**注意**  
X-Ray 应用采样算法确保跟踪有效，同时为 API 所接收的请求提供代表性样本。默认的采样算法是每秒钟 1 个请求，超过此限制的请求采样 5%。

您可以使用 API Gateway 管理控制台、API Gateway CLI 或Amazon开发工具包更改 API 的跟踪模式。

## X-Ray 跟踪的权限
<a name="set-up-xray-tracing-permissions"></a>

当您在一个阶段上启用 X-Ray 跟踪时，如果服务相关角色不存在，则 API Gateway 会在您的账户中创建该角色。该角色被命名为 `AWSServiceRoleForAPIGateway`，且将 `APIGatewayServiceRolePolicy` 托管策略附加于此。有关服务相关角色的更多信息，请参阅[使用服务相关角色](https://docs.amazonaws.cn/IAM/latest/UserGuide/using-service-linked-roles.html)。

## 在 API Gateway 控制台中启用 X-Ray 跟踪
<a name="apigateway-xray-console-setup"></a>

您可以使用 Amazon API Gateway 控制台在 API 阶段上启用活动的跟踪。

这些步骤假设您已将 API 部署到阶段。

1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.amazonaws.cn/apigateway)。

1. 选择您的 API，然后在主导航窗格中选择**阶段**。

1. 在**阶段**窗格中，选择阶段。

1. 在**日志和跟踪**部分中，选择**编辑**。

1. 要启用活动的 X-Ray 跟踪，请选择 **X-Ray 跟踪**以开启 X-Ray 跟踪。

1. 选择**保存更改**。

一旦您已为 API 阶段启用了 X-Ray，则可以使用 X-Ray 管理控制台查看跟踪和服务地图。

## 使用 API Gateway CLI 启用 Amazon X-Ray 跟踪
<a name="apigateway-xray-cli-setup"></a>

使用以下 [create-stage](https://docs.amazonaws.cn/cli/latest/reference/apigateway/create-stage.html) 命令创建具有活动 X-Ray 跟踪的阶段：

```
aws apigateway create-stage \
    --rest-api-id rest-api-id \
    --stage-name stage-name \
    --deployment-id deployment-id \
    --region region \
    --tracing-enabled=true
```

输出将与以下内容类似：

```
{
    "tracingEnabled": true, 
    "stageName": stage-name, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": deployment-id, 
    "lastUpdatedDate": 1533849811, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}
```

使用以下 [create-stage](https://docs.amazonaws.cn/cli/latest/reference/apigateway/create-stage.html) 命令创建没有活动 X-Ray 跟踪的阶段：

```
aws apigateway create-stage \
    --rest-api-id rest-api-id \
    --stage-name stage-name \
    --deployment-id deployment-id \
    --region region \
    --tracing-enabled=false
```

输出将与以下内容类似：

```
{
    "tracingEnabled": false, 
    "stageName": stage-name, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": deployment-id, 
    "lastUpdatedDate": 1533849811, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}
```

使用以下 [update-stage](https://docs.amazonaws.cn/cli/latest/reference/apigateway/update-stage.html) 为已部署 API 启用活动 X-Ray 跟踪：

```
aws apigateway update-stage \
    --rest-api-id rest-api-id \
    --stage-name stage-name \
    --patch-operations op=replace,path=/tracingEnabled,value=true
```

使用以下 [update-stage](https://docs.amazonaws.cn/cli/latest/reference/apigateway/update-stage.html) 为已部署 API 停用活动 X-Ray 跟踪：

```
aws apigateway update-stage \
    --rest-api-id rest-api-id \
    --stage-name stage-name \
    --region region \
    --patch-operations op=replace,path=/tracingEnabled,value=false
```

输出将与以下内容类似：

```
{
    "tracingEnabled": false, 
    "stageName": stage-name, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": deployment-id, 
    "lastUpdatedDate": 1533850033, 
    "createdDate": 1533849811, 
    "methodSettings": {}
}
```

一旦您已为 API 阶段启用了 X-Ray，请使用 X-Ray CLI 检索跟踪信息。有关更多信息，请参阅[将 API 与 Amazon CLI 一起使用](https://docs.amazonaws.cn/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial)。