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

# 在 API Gateway 中設定 WebSocket API 的記錄
<a name="websocket-api-logging"></a>

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

若要提升您的安全狀態，建議您在 `ERROR` 或 `INFO` 層級使用執行記錄。您可能需要這樣做，才能符合各種合規架構。如需詳細資訊，請參閱《AWS Security Hub 使用者指南》**中的 [Amazon API Gateway 控制項](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)。

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

如需有關如何設定 CloudWatch 記錄功能的指示，請參閱[使用 API Gateway 主控台設定 CloudWatch API 記錄功能](set-up-logging.md#set-up-access-logging-using-console)。

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


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

一些常用存取日誌格式範例會顯示在 API Gateway 主控台中，並列出如下。
+ `CLF` ([通用日誌格式](https://httpd.apache.org/docs/current/logs.html#common))：

  ```
  $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`)，以便在每個記錄項目的結尾加入新行。