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

# AWS X-Ray 使用 API Gateway REST APIs設定
<a name="apigateway-enabling-xray"></a>

本節提供如何使用 API Gateway REST API 設定 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) 的詳細資訊。

**Topics**
+ [API Gateway 的 API Gateway 追蹤模式](#apigateway-tracing-modes)
+ [X-Ray 追蹤的許可](#set-up-xray-tracing-permissions)
+ [在 API Gateway 主控台中啟用 X-Ray 追蹤](#apigateway-xray-console-setup)
+ [使用 API Gateway CLI 啟用 AWS X-Ray 追蹤](#apigateway-xray-cli-setup)

## API Gateway 的 API Gateway 追蹤模式
<a name="apigateway-tracing-modes"></a>

透過應用程式的請求路徑是使用追蹤 ID 進行追蹤。追蹤會收集由單一請求所產生的所有區段，一般為 HTTP `GET` 或 `POST` 請求。

API Gateway API 有兩種追蹤模式：
+ **Passive (被動)**：如果您未在 API 階段上啟用 X-Ray 追蹤，這是預設設定。此方法表示僅有在上游服務已啟用 X-Ray 的情況下，系統才會追蹤 API Gateway API。
+ **Active (主動)**：API Gateway API 階段具有此設定時，API Gateway 會根據 X-Ray 指定的取樣演算法來自動對 API 呼叫請求取樣。

  在階段上啟用主動追蹤時，API Gateway 會在您的帳戶中建立服務連結角色 (若該角色不存在)。角色名為 `AWSServiceRoleForAPIGateway` 並會將 `APIGatewayServiceRolePolicy` 受管政策附加到該角色。如需服務連結角色的詳細資訊，請參閱[使用服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。
**注意**  
X-Ray 會套用取樣演算法以確保追蹤的效率，同時提供 API 收到之請求的代表範本。預設的取樣演算法為每秒 1 個請求，並對超過該限制的請求量取樣 5%。

您可以使用 API Gateway 管理主控台、API Gateway CLI 或 AWS SDK 來變更 API 的追蹤模式。

## X-Ray 追蹤的許可
<a name="set-up-xray-tracing-permissions"></a>

在階段上啟用 X-Ray 追蹤時，API Gateway 會在您的帳戶中建立服務連結角色 (若該角色不存在)。角色名為 `AWSServiceRoleForAPIGateway` 並會將 `APIGatewayServiceRolePolicy` 受管政策附加到該角色。如需服務連結角色的詳細資訊，請參閱[使用服務連結角色](https://docs.aws.amazon.com/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. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 選擇您的 API，然後在主導覽窗格中選擇**階段**。

1. 在**階段**窗格中，選擇一個階段。

1. 在**日誌和追蹤**區段中，選擇**編輯**。

1. 若要啟用主動 X-Ray 追蹤，選取 **X-Ray 追蹤**以開啟 X-Ray 追蹤。

1. 選擇**儲存變更**。

為您的 API 階段啟用 X-Ray 之後，您可以使用 X-Ray 管理主控台來查看追蹤和服務對應。

## 使用 API Gateway CLI 啟用 AWS X-Ray 追蹤
<a name="apigateway-xray-cli-setup"></a>

以下 [create-stage](https://docs.aws.amazon.com/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.aws.amazon.com/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.aws.amazon.com/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.aws.amazon.com/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 來擷取追蹤資訊。如需詳細資訊，請參閱[搭配 CLI AWS 使用 X-Ray API](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial)。