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

# API Gateway 存取記錄的變數
<a name="api-gateway-variables-for-access-logging"></a>

 在存取記錄中，您身為 API 開發人員且想要記錄誰已存取您的 API 以及發起人存取 API 的方式。您可以建立自己的日誌群組，或選擇由 API Gateway 管理的現有日誌群組。若要指定存取詳細資訊，您可以使用下列區分大小寫的 `$context` 變數。

如需資料轉換的參考變數清單，請參閱 [用於 API Gateway 資料轉換的變數](api-gateway-mapping-template-reference.md)。


| 參數 | 說明 | 
| --- | --- | 
| \$1context.accountId |  API 擁有者 AWS 的帳戶 ID。  | 
| \$1context.apiId |  API Gateway 指派給您 API 的識別碼。  | 
| \$1context.authorize.error | 授權錯誤訊息。 | 
| \$1context.authorize.latency | 授權延遲 (以毫秒為單位)。 | 
| \$1context.authorize.status | 從授權嘗試傳回的狀態碼。 | 
| \$1context.authorizer.claims.property |  成功驗證方法發起人之後，從 Amazon Cognito 使用者集區傳回之宣告的屬性。如需詳細資訊，請參閱 [使用 Amazon Cognito 使用者集區做為授權方，藉以控制對 REST API 的存取](apigateway-integrate-with-cognito.md)。  呼叫 `$context.authorizer.claims` 會傳回 null。   | 
| \$1context.authorizer.error | 從授權方傳回的錯誤訊息。 | 
| \$1context.authorizer.integrationLatency | 授權方整合延遲 (以毫秒為單位)。 | 
| \$1context.authorizer.integrationStatus | 從 Lambda 授權方傳回的狀態碼。 | 
| \$1context.authorizer.latency | 授權方延遲 (以毫秒為單位)。 | 
| \$1context.authorizer.principalId |  與用戶端所傳送並從 API Gateway Lambda 授權方 (先前稱作自訂授權方) 所傳回之字符相關聯的主要使用者身分。如需詳細資訊，請參閱 [使用 API Gateway Lambda 授權方](apigateway-use-lambda-authorizer.md)。  | 
| \$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"` 字串。 對於*屬性*，唯一支援的特殊字元是底線 `(_)` 字元。 如需詳細資訊，請參閱[使用 API Gateway Lambda 授權方](apigateway-use-lambda-authorizer.md)。  | 
| \$1context.authorizer.requestId |  AWS 端點的請求 ID。 | 
| \$1context.authorizer.status | 從授權方傳回的狀態碼。 | 
| \$1context.authenticate.error | 從驗證嘗試傳回的錯誤訊息。 | 
| \$1context.authenticate.latency | 驗證延遲 (以毫秒為單位)。 | 
| \$1context.authenticate.status | 從驗證嘗試傳回的狀態碼。 | 
| \$1context.awsEndpointRequestId |   AWS 端點的請求 ID。  | 
| \$1context.cipherSuite |  在用戶端和 API Gateway 之間的 TLS 交握期間交涉的 IANA 格式密碼。 | 
| \$1context.customDomain.basePathMatched |  傳入請求相符的 API 映射路徑。適用於用戶端使用自訂網域名稱來存取 API 時。例如，如果用戶端向 `https://api.example.com/v1/orders/1234` 傳送請求，並且請求讓 API 映射與路徑 `v1/orders` 相符，則該值為 `v1/orders`。如需進一步了解，請參閱[使用 API 映射將 API 階段連線至 REST APIs 的自訂網域名稱](rest-api-mappings.md)。  | 
| \$1context.customDomain.routingRuleIdMatched | 傳入請求與其相符的路由規則。適用於用戶端使用自訂網域名稱來存取 API 時。如需詳細資訊，請參閱 [將 API 階段連線至 REST API 自訂網域名稱的路由規則](rest-api-routing-rules.md)。 | 
| \$1context.deploymentId | API 部署的 ID。 | 
| \$1context.domainName |  用來調用 API 的完整網域名稱。這應該與傳入的 `Host` 標頭相同。  | 
| \$1context.domainPrefix |  `$context.domainName` 的第一個標籤。  | 
| \$1context.endpointType | API 的端點類型。 | 
| \$1context.error.message |  包含 API Gateway 錯誤訊息的字串。此變數只能用於 Velocity 範本語言引擎無法處理的 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文映射範本及存取記錄中的簡單變數替換。如需詳細資訊，請參閱[使用 CloudWatch 指標監控 WebSocket API 執行](apigateway-websocket-api-logging.md)及[設定閘道回應以自訂錯誤回應](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。  | 
| \$1context.error.messageString | \$1context.error.message 的引用值，即 "\$1context.error.message"。 | 
| \$1context.error.responseType |  [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 的[類型](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)。此變數只能用於 Velocity 範本語言引擎無法處理的 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文映射範本及存取記錄中的簡單變數替換。如需詳細資訊，請參閱[使用 CloudWatch 指標監控 WebSocket API 執行](apigateway-websocket-api-logging.md)及[設定閘道回應以自訂錯誤回應](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。  | 
| \$1context.error.validationErrorString |  字串，其中包含詳細的驗證錯誤訊息。  | 
| \$1context.extendedRequestId | API Gateway 產生和指派給 API 請求的延伸 ID。延伸請求 ID 包含有助於偵錯和疑難排解的資訊。 | 
| \$1context.httpMethod |  使用的 HTTP 方法。有效值包含：`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` 和 `PUT`。  | 
| \$1context.identity.accountId |  與請求相關聯的 AWS 帳戶 ID。  | 
| \$1context.identity.apiKey |  對於需要 API 金鑰的 API 方法，此變數是與方法請求相關聯的 API 金鑰。對於不需要 API 金鑰的方法，此變數為 null。如需詳細資訊，請參閱 [API Gateway 中 REST API 的用量計畫和 API 金鑰](api-gateway-api-usage-plans.md)。  | 
| \$1context.identity.apiKeyId | 與需要 API 金鑰之 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)。  | 
| \$1context.identity.sourceIp |  對 API Gateway 端點提出請求之即時 TCP 連線的來源 IP 位址。  | 
| \$1context.identity.clientCert.clientCertPem |  用戶端在交互 TLS 驗證期間所呈現的 PEM 編碼用戶端憑證。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。  | 
| \$1context.identity.clientCert.subjectDN |  用戶端提供之憑證主體的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。  | 
| \$1context.identity.clientCert.issuerDN |  用戶端提供之憑證發行者的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。  | 
| \$1context.identity.clientCert.serialNumber |  憑證的序號。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。  | 
| \$1context.identity.clientCert.validity.notBefore |  憑證無效之前的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。  | 
| \$1context.identity.clientCert.validity.notAfter |  憑證無效之後的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。  | 
|  \$1context.identity.vpcId | 對 API Gateway 端點提出請求之 VPC 的 VPC ID。 | 
|  \$1context.identity.vpceId |  對 API Gateway 端點提出請求之 VPC 端點的 VPC 端點 ID。只會在您擁有私有 API 時顯示。  | 
| \$1context.identity.user |  將針對資源存取授權之使用者的主體識別符。支援使用 IAM 授權的資源。  | 
| \$1context.identity.userAgent |  API 發起人的 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 標頭。  | 
| \$1context.identity.userArn |  身分驗證之後識別之有效使用者的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱[https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)。  | 
| \$1context.integration.error | 從整合傳回的錯誤訊息。 | 
| \$1context.integration.integrationStatus | 對於 Lambda 代理整合，從 傳回的狀態碼 AWS Lambda，而不是從後端 Lambda 函數程式碼傳回的狀態碼。 | 
| \$1context.integration.latency | 整合延遲 (以毫秒為單位)。等同於 \$1context.integrationLatency。 | 
| \$1context.integration.requestId |  AWS 端點的請求 ID。等同於 \$1context.awsEndpointRequestId。 | 
| \$1context.integration.responseTransferMode | 整合的回應傳輸模式。可以是 BUFFERED 或 STREAMED。 | 
| \$1context.integration.status | 從整合傳回的狀態碼。對於 Lambda 代理整合而言，這是您的 Lambda 函數程式碼傳回的狀態碼。 | 
| \$1context.integration.timeToAllHeaders | 從用戶端接收所有整合回應標頭時，API Gateway 與 建立整合連線之間的時間。 | 
| \$1context.integration.timeToFirstContent | API Gateway 在收到第一個內容位元組時建立與 的整合連線之間的時間。 | 
| \$1context.integrationLatency | 整合延遲 (以毫秒為單位)。 | 
| \$1context.integrationStatus | 對於 Lambda 代理整合，此參數代表從 傳回的狀態碼 AWS Lambda，而不是從後端 Lambda 函數程式碼傳回的狀態碼。 | 
| \$1context.isCanaryRequest |  如果請求導向 Canary，則傳回 `true`；如果請求未導向 Canary，則傳回 `false`。只會在啟用 Canary 時顯示。 | 
| \$1context.path | 請求路徑。例如，對於 https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child 的非代理請求 URL，\$1context.path 值是 /\$1stage\$1/root/child。 | 
| \$1context.protocol | 請求通訊協定，例如 HTTP/1.1。 API Gateway API 可以接受 HTTP/2 請求，但 API Gateway 會使用 HTTP/1.1 將請求傳送至後端整合。因此，即使用戶端傳送使用 HTTP/2 的請求，請求通訊協定也會記錄為 HTTP/1.1。   | 
| \$1context.requestId |  請求的 ID。用戶端可以覆寫此請求 ID。使用 `$context.extendedRequestId` 即可取得 API Gateway 產生的唯一請求 ID。  | 
| \$1context.requestOverride.header.header\$1name |  請求標題會覆寫。如果此參數已經定義，它包含要使用的標頭 (而不是在 **Integration Request (整合請求)** 窗格中定義的 **HTTP Headers (HTTP 標頭)**)。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。  | 
| \$1context.requestOverride.path.path\$1name |  請求路徑會覆寫。如果此參數已經定義，它包含要使用的請求路徑 (而不是在 **Integration Request (整合請求)** 窗格中定義的 **URL Path Parameters (URL 路徑參數)**)。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。  | 
| \$1context.requestOverride.querystring.querystring\$1name |  請求查詢字串會覆寫。如果此參數已經定義，它包含要使用的請求查詢字串 (而不是在 **Integration Request (整合請求) ** 窗格中定義的 **URL Query String (URL 查詢字串)**)。如需詳細資訊，請參閱[覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。  | 
| \$1context.responseLatency | 回應延遲 (以毫秒為單位)。 | 
| \$1context.responseLength | 回應承載長度 (以位元組為單位)。 | 
| \$1context.responseOverride.header.header\$1name | 回應標題會覆寫。如果此參數已經定義，它包含要傳回的標頭 (而不是在 Integration Response (整合回應) 窗格中定義為 Default mapping (預設映射) 的 Response header (回應標頭))。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。 | 
| \$1context.responseOverride.status | 回應狀態碼會覆寫。如果此參數已經定義，它包含要傳回的狀態碼 (而不是在 Integration Response (整合回應) 窗格中定義為 Default mapping (預設映射) 的 Method response status (方法回應狀態))。如需詳細資訊，請參閱 [覆寫 API Gateway 中 REST API 的 API 請求和回應參數及狀態碼](apigateway-override-request-response-parameters.md)。 | 
| \$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.resourceId |  API Gateway 指派給您的資源的識別碼。  | 
| \$1context.resourcePath |  您資源的路徑。例如，對於非代理請求 URI `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`，`$context.resourcePath` 值是 `/root/child`。如需詳細資訊，請參閱 [教學：建立具有 HTTP 非代理整合的 REST API](api-gateway-create-api-step-by-step.md)。  | 
| \$1context.stage |  API 請求的部署階段 (例如，`Beta` 或 `Prod`)。  | 
| \$1context.status | 方法回應狀態。 | 
| \$1context.tlsVersion |  在用戶端和 API Gateway 之間的 TLS 交握期間交涉的 TLS 版本。 | 
| \$1context.waf.error | 從 傳回的錯誤訊息 AWS WAF。 | 
| \$1context.waf.latency | 以毫秒為單位的 AWS WAF 延遲。 | 
| \$1context.waf.status | 從 傳回的狀態碼 AWS WAF。 | 
| \$1context.xrayTraceId |  X-Ray 追蹤的追蹤 ID。如需詳細資訊，請參閱[AWS X-Ray 使用 API Gateway REST APIs設定](apigateway-enabling-xray.md)。  | 
| \$1context.wafResponseCode |  從 [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) 收到的回應：`WAF_ALLOW` 或 `WAF_BLOCK`。若該階段與 web ACL 不相關聯，將不會設定此值。如需詳細資訊，請參閱 [使用 AWS WAF 來保護 API Gateway APIs 中的 REST API](apigateway-control-access-aws-waf.md)。  | 
| \$1context.webaclArn |  Web ACL 的完整 ARN，用來決定是否允許或封鎖請求。若該階段與 web ACL 不相關聯，將不會設定此值。如需詳細資訊，請參閱[使用 AWS WAF 來保護 API Gateway APIs 中的 REST API](apigateway-control-access-aws-waf.md)。  |