使用 API Gateway REST API 設定 AWS X-Ray - Amazon API Gateway
API Gateway 的 API Gateway 追蹤模式X-Ray 追蹤的許可在 API Gateway 主控台中啟用 X-Ray 追蹤使用 API Gateway API CLI 來啟用 X-Ray 追蹤

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

使用 API Gateway REST API 設定 AWS X-Ray

本節提供如何使用 API Gateway REST API 設定 AWS X-Ray 的詳細資訊。

API Gateway 的 API Gateway 追蹤模式

透過應用程式的請求路徑是使用追蹤 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 受管政策附加到該角色。如需服務連結角色的詳細資訊，請參閱使用服務連結角色。

    注意

    X-Ray 會套用取樣演算法以確保追蹤的效率，同時提供 API 收到之請求的代表範本。預設的取樣演算法為每秒 1 個請求，並對超過該限制的請求量取樣 5%。

您可以使用 API Gateway 管理主控台、API Gateway CLI 或 AWS 軟體開發套件來為 API 變更追蹤模式。

X-Ray 追蹤的許可

在階段上啟用 X-Ray 追蹤時，API Gateway 會在您的帳戶中建立服務連結角色 (若該角色不存在)。角色名為 AWSServiceRoleForAPIGateway 並會將 APIGatewayServiceRolePolicy 受管政策附加到該角色。如需服務連結角色的詳細資訊，請參閱使用服務連結角色。

在 API Gateway 主控台中啟用 X-Ray 追蹤

您可以使用 Amazon API Gateway 主控台在 API 階段上啟用主動追蹤。

這些步驟假設您已經將 API 部署到階段。

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

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

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

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

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

  6. 選擇 Save changes (儲存變更)。

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

使用 API Gateway CLI 啟用 AWS X-Ray 追蹤

若要在建立階段時使用 AWS CLI 來啟用 API 階段的主動 X-Ray 追蹤，請呼叫 create-stage 命令，如以下範例所示：

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": {}
}

若要在建立階段時使用 AWS CLI 來停用 API 階段的主動 X-Ray 追蹤，請呼叫 create-stage 命令，如以下範例所示：

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": {}
}

若要使用 AWS CLI 來啟用已部署 API 的主動 X-Ray 追蹤，請呼叫 update-stage 命令，如下所示：

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

若要使用 AWS CLI 來停用已部署 API 的主動 X-Ray 追蹤，請呼叫 update-stage 命令，如以下範例所示：

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 使用 AWS X-Ray API。