# API Gateway REST API で AWS X-Ray を設定する
<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 での X-Ray のトレースモード](#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 での X-Ray のトレースモード
<a name="apigateway-tracing-modes"></a>

アプリケーションを経由するリクエストのパスは、トラック ID を使用して追跡されます。トレースでは、1 つのリクエスト (通常は HTTP `GET` または `POST` リクエスト) で生成されたセグメントをすべて収集します。

API Gateway の API のトレースには、次の 2 つのモードがあります。
+ **パッシブ**: API のステージに対して X-Ray によるトレースを有効にしていない場合は、これがデフォルトの設定です。この方法では、API Gateway の API は、アップストリームのサービスで X-Ray が有効になっている場合にのみトレースされます。
+ **アクティブ**: 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 秒間につき 1 リクエストで、この制限を超えた場合はリクエストの 5 パーセントがサンプリングされます。

API のトレースモードは、API Gateway マネジメントコンソール、API Gateway CLI、または AWS SDK を使用して変更できます。

## 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. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。

1. API を選択し、メインナビゲーションペインで **[ステージ]** を選択します。

1. **[ステージ]** ペインで、ステージを選択します。

1. **[ログおよびトレース]** セクションで **[編集]** を選択します。

1. X-Ray によるアクティブトレースを有効にするには、**[X-Ray トレース]** を選択して、X-Ray トレースを有効にします。

1. **[Save changes]** (変更の保存) をクリックします。

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 を使用してトレース情報を取得します。詳細については、「[AWS CLI での X-Ray API の使用](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial)」を参照してください。