View a markdown version of this page

REST APIs執行記錄 - Amazon API Gateway
標準執行記錄執行日誌的 Amazon CloudWatch Logs 交付

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

REST APIs執行記錄

執行記錄會記錄 API Gateway 處理 API 請求所採取的動作。記錄的資料包括錯誤、執行追蹤、請求和回應參數值或承載、Lambda 授權方使用的資料、是否需要 API 金鑰，以及是否啟用用量計劃。API Gateway 會從記錄的資料修訂授權標頭、API 金鑰值和類似的敏感請求參數。

若要提升您的安全狀態，建議您在 ERROR 或 INFO 層級使用執行記錄。您可能需要這樣做，才能符合各種合規架構。如需詳細資訊，請參閱《AWS Security Hub 使用者指南》中的 Amazon API Gateway 控制項。

標準執行記錄

當您在階段上啟用執行記錄時，API Gateway 會自動建立和管理 CloudWatch Logs 日誌群組。日誌群組名為 API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}。在每個日誌群組中，日誌會分為依上次事件時間排序的日誌串流。

使用標準執行記錄：

  • 日誌事件被截斷為 1 KB。

  • API Gateway 會管理日誌群組名稱。您無法選擇日誌群組名稱或將日誌直接傳送到 Amazon S3 或 Firehose。

若要啟用標準執行記錄，請將階段loggingLevel上的 設定為 ERROR或 INFO。無需其他組態。

許可

若要啟用 CloudWatch Logs，您必須授予 API Gateway 為您的帳戶將日誌讀取和寫入 CloudWatch 的許可。AmazonAPIGatewayPushToCloudWatchLogs 受管政策具有所有必要的許可。

使用 建立 IAM 角色apigateway.amazonaws.com做為其信任的實體，附加上述政策，並在您帳戶的 cloudWatchRoleArn 屬性上設定 IAM 角色 ARN。您必須針對要啟用 CloudWatch Logs 的每個 AWS 區域分別設定此屬性。

注意

API Gateway 會呼叫 AWS Security Token Service 來擔任 IAM 角色，因此請務必為 區域啟用 AWS STS 。如需詳細資訊，請參閱在 AWS 區域中管理 AWS STS。

啟用執行記錄 （主控台）

開始之前，請將 API 部署至階段，並為您的帳戶設定適當的 CloudWatch Logs 角色 ARN。

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

  2. 在主導覽窗格中，選擇設定，然後在記錄下選擇編輯。

  3. 針對 CloudWatch 日誌角色 ARN，輸入具有適當許可的 IAM 角色 ARN。您需要針對每個使用 APIs建立 API AWS 帳戶 的 執行此操作一次。

  4. 在主要導覽窗格中，選擇 APIs、選擇 REST API，然後選擇階段。

  5. 選擇階段，然後在日誌和追蹤區段中，選擇編輯。

  6. 從 CloudWatch Logs 下拉式功能表中選取記錄層級：

    • 關閉 – API Gateway 不會記錄此階段的請求。

    • 僅限錯誤 – API Gateway 僅記錄錯誤。

    • 錯誤和資訊日誌 – API Gateway 會記錄所有事件。

  7. （選用） 選取資料追蹤以記錄完整的請求和回應資料。這可能會導致記錄敏感資料。

    注意

    建議您不要針對生產 API 使用資料追蹤。

  8. (選用) 選取詳細指標以開啟詳細的 CloudWatch 指標。如需詳細資訊，請參閱使用 Amazon CloudWatch 指標監控 REST API 執行。

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

當您更新階段設定時，不需要重新部署 API。

啟用執行記錄 (CloudFormation)

使用階段資源上的 MethodSettings 屬性來啟用執行記錄。

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO

若要啟用 CloudWatch Logs，您必須授予 API Gateway 為您的帳戶將日誌讀取和寫入 CloudWatch 的許可。若要深入了解，請參閱《AWS CloudFormation  使用者指南》中的將帳戶與 IAM 角色建立關聯。

執行日誌的 Amazon CloudWatch Logs 交付

Amazon CloudWatch Logs 交付提供執行日誌的替代路徑。您可以設定傳送，將執行日誌傳送至您擁有和控制的目的地，而不是寫入 API Gateway 受管日誌群組。

使用 Amazon CloudWatch Logs 交付：

  • 日誌事件最多可達 1 MB，可擷取更完整的請求和回應資料。超過 1 MB 的承載仍會遭到截斷。

  • 您可以選擇目的地：您自己的 CloudWatch Logs 日誌群組、Amazon S3 儲存貯體或 Firehose 串流。

  • 您可以同時將日誌傳送至多個目的地。

  • 您可以控制日誌群組組態，包括命名和保留。

重要

CloudWatch Logs 交付會取代標準執行記錄。當您設定交付時，API Gateway 會停止寫入自動受管日誌群組。您不能在同一階段同時使用這兩個路徑。

當您建立交付時，API Gateway 會將執行日誌路由到您設定的目的地，而不是自動管理的日誌群組。當您刪除交付時，執行日誌會自動繼續流向自動管理的日誌群組。除了loggingLevel將 設定為 ERROR或 的先決條件之外，不需要進行任何 API Gateway 組態變更INFO。

注意

日誌交付是最佳作法。在極少數情況下，可能無法傳遞某些日誌事件。

警告

啟用日誌交付之前，請更新參考自動受管日誌群組 () 的任何儀表板、警示或訂閱篩選條件API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}。交付處於作用中狀態後，該日誌群組不會再收到新事件。

下表將標準執行記錄與 Amazon CloudWatch Logs 交付進行比較。

標準執行記錄 Amazon CloudWatch Logs 交付
日誌事件大小上限 1 KB 1 MB
目的地 CloudWatch Logs （受管日誌群組） CloudWatch Logs、Amazon S3、Firehose （您自己的資源）
多個目的地 否 是
日誌群組名稱 由 API Gateway 修正 您可以選擇
設定 啟用記錄時自動執行 需要建立 Amazon CloudWatch Logs 交付
先決條件 loggingLevel 設定為 ERROR或 INFO loggingLevel 設定為 ERROR或 INFO
注意

如果您在設定交付OFF之後loggingLevel將 設定為 ，則不會產生或交付執行日誌。您的交付目的地會保持設定狀態，但不會接收任何資料。

若要建立交付，請參閱 建立 REST API 執行日誌的日誌交付。