設定 WebSocket API 的記錄

您可以啟用記錄功能，將記錄寫入記 CloudWatch 錄檔。API 記錄有兩種類型 CloudWatch：執行記錄和存取記錄。在執行記錄中，API Gateway 會管理記 CloudWatch 錄檔。此程序包含建立日誌群組和日誌串流，以及向日誌串流報告任何發起人的請求和回應。

在存取記錄中，您身為 API 開發人員且想要記錄誰已存取您的 API 以及發起人存取 API 的方式。您可以建立自己的日誌群組，或選擇由 API Gateway 管理的現有日誌群組。若要指定存取權詳細資料，您可以選取 $context 變數 (以所選擇格式表示)，以及選擇日誌群組作為目標。

如需如何設定 CloudWatch 記錄的指示，請參閱使用 CloudWatch API Gateway 主控台設定 API 記錄。

當您指定 Log Format (日誌格式)，您可以選擇要記錄哪些環境變數。支援下列變數。

參數	描述
$context.apiId	API Gateway 指派給您 API 的識別碼。
$context.authorize.error	授權錯誤訊息。
$context.authorize.latency	授權延遲 (以毫秒為單位)。
$context.authorize.status	從授權嘗試傳回的狀態碼。
$context.authorizer.error	從授權方傳回的錯誤訊息。
$context.authorizer.integrationLatency	Lambda 授權方延遲 (以毫秒為單位)。
$context.authorizer.integrationStatus	從 Lambda 授權方傳回的狀態碼。
$context.authorizer.latency	授權方延遲 (以毫秒為單位)。
$context.authorizer.requestId	AWS 端點的要求識別碼。
$context.authorizer.status	從授權方傳回的狀態碼。
$context.authorizer.principalId	與用戶端所傳送並從 API Gateway Lambda 授權方 Lambda 函數所傳回之權杖建立關聯的主要使用者識別。(Lambda 授權方之前稱為自訂授權方。)
$context.authorizer.property	API Gateway Lambda 授權方函數所傳回 context 映射之指定索引鍵/值組的字串化值。例如，如果授權方傳回下列 context 映射： "context" : { "key": "value", "numKey": 1, "boolKey": true } 呼叫 $context.authorizer.key 會傳回 "value" 字串、呼叫 $context.authorizer.numKey 會傳回 "1" 字串，而呼叫 $context.authorizer.boolKey 會傳回 "true" 字串。
$context.authenticate.error	從驗證嘗試傳回的錯誤訊息。
$context.authenticate.latency	驗證延遲 (以毫秒為單位)。
$context.authenticate.status	從驗證嘗試傳回的狀態碼。
$context.connectedAt	Epoch 格式化連線時間。
$context.connectionId	連線的唯一 ID，可用來回呼用戶端。
$context.domainName	WebSocket API 的網域名稱。此可用於回呼用戶端 (非硬式編碼的值)。
$context.error.message	包含 API Gateway 錯誤訊息的字串。
$context.error.messageString	$context.error.message 的引用值，即 "$context.error.message"。
$context.error.responseType	錯誤回應類型。
$context.error.validationErrorString	包含詳細驗證錯誤訊息的字串。
$context.eventType	事件類型：CONNECT、MESSAGE 或 DISCONNECT。
$context.extendedRequestId	等同於 $context.requestId。
$context.identity.accountId	與請求相關聯的 AWS 帳戶 ID。
$context.identity.apiKey	與啟用金鑰之 API 請求建立關聯的 API 擁有者金鑰。
$context.identity.apiKeyId	與啟用金鑰之 API 請求建立關聯的 API 金鑰 ID。
$context.identity.caller	已簽署請求之發起人的主體識別符。支援使用 IAM 授權的路由。
$context.identity.cognitoAuthenticationProvider	提出請求的發起人所使用的 Amazon Cognito 身分驗證提供者清單 (以逗號分隔)。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 例如，適用於 Amazon Cognito 使用者集區的身分，cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim 如需詳細資訊，請參閱 Amazon Cognito 開發人員指南中的使用聯合身分。
$context.identity.cognitoAuthenticationType	提出請求的發起人的 Amazon Cognito 身分驗證類型。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。可能的值包括用於已驗證身分的 authenticated 和未經驗證身分的 unauthenticated。
$context.identity.cognitoIdentityId	提出請求的發起人的 Amazon Cognito 身分 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。
$context.identity.cognitoIdentityPoolId	提出請求的發起人的 Amazon Cognito 身分集區 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。
$context.identity.principalOrgId	AWS 組織 ID。支援使用 IAM 授權的路由。
$context.identity.sourceIp	對 API Gateway 提出請求之 TCP 連線的來源 IP 地址。
$context.identity.user	將針對資源存取授權之使用者的主體識別符。支援使用 IAM 授權的路由。
$context.identity.userAgent	API 發起人的使用者代理程式。
$context.identity.userArn	身分驗證之後識別之有效使用者的 Amazon Resource Name (ARN)。
$context.integration.error	從整合傳回的錯誤訊息。
$context.integration.integrationStatus	對於 Lambda 代理整合，狀態碼會從後端 Lambda 函數程式碼傳回 AWS Lambda，而不是從後端 Lambda 函數
$context.integration.latency	整合延遲 (以毫秒為單位)。等同於 $context.integrationLatency。
$context.integration.requestId	AWS 端點的要求識別碼。等同於 $context.awsEndpointRequestId。
$context.integration.status	從整合傳回的狀態碼。對於 Lambda 代理整合而言，這是您的 Lambda 函數程式碼傳回的狀態碼。等同於 $context.integrationStatus。
$context.integrationLatency	毫秒的整合延遲僅可用於存取記錄。
$context.messageId	訊息的伺服器端唯一 ID。僅在 $context.eventType 為 MESSAGE 時可用。
$context.requestId	與 $context.extendedRequestId 相同。
$context.requestTime	CLF 格式化請求時間 (dd/MMM/yyyy:HH:mm:ss +-hhmm)。
$context.requestTimeEpoch	Epoch 格式化的要求時間，以毫秒為單位。
$context.routeKey	所選路由金鑰。
$context.stage	API 呼叫的部署階段 (例如，Beta 或 Prod)。
$context.status	回應狀態。
$context.waf.error	從傳回的錯誤訊息 AWS WAF。
$context.waf.latency	以毫秒為單位的 AWS WAF 延遲。
$context.waf.status	從傳回的狀態碼 AWS WAF。

一些常用存取日誌格式範例會顯示在 API Gateway 主控台中，並列出如下。

• CLF (通用日誌格式)：

  $context.identity.sourceIp $context.identity.caller \
  $context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
  $context.status $context.requestId

  延續字符 (\) 代表作為一種視覺輔助。記錄格式必須是單行。您可以在記錄格式的結尾新增新行字元 (\n)，以便在每個記錄項目的結尾加入新行。

• JSON:

  {
  "requestId":"$context.requestId", \
  "ip": "$context.identity.sourceIp", \
  "caller":"$context.identity.caller", \
  "user":"$context.identity.user", \
  "requestTime":"$context.requestTime", \
  "eventType":"$context.eventType", \
  "routeKey":"$context.routeKey", \
  "status":"$context.status", \
  "connectionId":"$context.connectionId"
  }

  延續字符 (\) 代表作為一種視覺輔助。記錄格式必須是單行。您可以在記錄格式的結尾新增新行字元 (\n)，以便在每個記錄項目的結尾加入新行。

• XML:

  <request id="$context.requestId"> \
   <ip>$context.identity.sourceIp</ip> \
   <caller>$context.identity.caller</caller> \
   <user>$context.identity.user</user> \
   <requestTime>$context.requestTime</requestTime> \
   <eventType>$context.eventType</eventType> \
   <routeKey>$context.routeKey</routeKey> \
   <status>$context.status</status> \
   <connectionId>$context.connectionId</connectionId> \
  </request>

  延續字符 (\) 代表作為一種視覺輔助。記錄格式必須是單行。您可以在記錄格式的結尾新增新行字元 (\n)，以便在每個記錄項目的結尾加入新行。

• CSV (逗號分隔值)：

  $context.identity.sourceIp,$context.identity.caller, \
  $context.identity.user,$context.requestTime,$context.eventType, \
  $context.routeKey,$context.connectionId,$context.status, \
  $context.requestId

  延續字符 (\) 代表作為一種視覺輔助。記錄格式必須是單行。您可以在記錄格式的結尾新增新行字元 (\n)，以便在每個記錄項目的結尾加入新行。