本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 API Gateway 中監控的 WebSocket API 您可以使用 CloudWatch 指標和 CloudWatch Logs 來監控 WebSocket API。藉由結合日誌和指標，您可以記錄錯誤並監控 API 的效能。 **注意** 在下列情況下，API Gateway 可能無法產生日誌和指標： 413 請求實體過大錯誤 過多的 429 請求過多錯誤 400 系列錯誤，來自傳送至沒有 API 映射自訂網域的要求 由於內部失敗造成的 500 系列錯誤 **Topics** + [使用 CloudWatch 指標監控 WebSocket API 執行](apigateway-websocket-api-logging.md) + [在 API Gateway 中設定 WebSocket API 的記錄](websocket-api-logging.md) # 使用 CloudWatch 指標監控 WebSocket API 執行 您可以使用 [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) 指標來監控 WebSocket API。該組態與用於 REST API 的組態類似。如需更多詳細資訊，請參閱 [使用 Amazon CloudWatch 指標監控 REST API 執行](monitoring-cloudwatch.md)。 WebSocket API 支援以下指標： | 指標 | 描述 | | --- | --- | | ConnectCount | 傳送到 \$1connect 路由整合的訊息數。 | | MessageCount | 傳送到 WebSocket API 的訊息數 (來自用戶端或傳送到用戶端)。 | | IntegrationError | 從整合傳回 4XX/5XX 回應的請求數。 | | ClientError | 擁有在整合受到叫用前由 API Gateway 傳回的 4XX 回應之請求數。 | | ExecutionError | 呼叫整合時發生的錯誤。 | | IntegrationLatency | API Gateway 將請求傳送至整合與 API Gateway 從整合接收回應之間的時間差異。受回呼和偽裝整合抑制。 | 您可以使用下表中的維度來篩選 API Gateway 指標。 | 維度 | 描述 | | --- | --- | | ApiId | 篩選具指定 API ID 之 API 的 API Gateway 指標。 | | ApiId、階段 | 篩選具指定 API ID 與階段 ID 之 API 階段的 API Gateway 指標。 | | ApiId、方法、資源、階段 | 篩選具指定 API ID、階段 ID、資源路徑和路由 ID 之 API 方法的 API Gateway 指標。 除非您已明確啟用詳細的 CloudWatch 指標，否則 API Gateway 不會傳送這類指標。您可以透過呼叫 API Gateway V2 REST API 的 [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) 動作，將 `detailedMetricsEnabled` 屬性更新為 `true`。或者，您可以呼叫 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) AWS CLI 命令，將 `DetailedMetricsEnabled` 屬性更新為 `true`。啟用這類指標會產生您帳戶的額外費用。如需定價資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。 | # 在 API Gateway 中設定 WebSocket API 的記錄 您可以啟用記錄功能，將日誌寫入 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` 映射： 
"context" : {
                            "key": "value",
                            "numKey": 1,
                            "boolKey": true
                            }
呼叫 `$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`: ``` \ $context.identity.sourceIp \ $context.identity.caller \ $context.identity.user \ $context.requestTime \ $context.eventType \ $context.routeKey \ $context.status \ $context.connectionId \ ``` 延續字符 (`\`) 代表作為一種視覺輔助。記錄格式必須是單行。您可以在記錄格式的結尾新增新行字元 (`\n`)，以便在每個記錄項目的結尾加入新行。 + `CSV` (逗號分隔值)： ``` $context.identity.sourceIp,$context.identity.caller, \ $context.identity.user,$context.requestTime,$context.eventType, \ $context.routeKey,$context.connectionId,$context.status, \ $context.requestId ``` 延續字符 (`\`) 代表作為一種視覺輔助。記錄格式必須是單行。您可以在記錄格式的結尾新增新行字元 (`\n`)，以便在每個記錄項目的結尾加入新行。