API Gateway 存取記錄的變數

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

如需資料轉換的參考變數清單，請參閱 API Gateway 資料轉換的變數。


                    $context.accountId


                    $context.apiId


                    $context.authorize.error

授權錯誤訊息。


                    $context.authorize.latency

授權延遲 (以毫秒為單位)。


                    $context.authorize.status

從授權嘗試傳回的狀態碼。


                    $context.authorizer.claims.
                    
                     property


                    $context.authorizer.error

從授權方傳回的錯誤訊息。


                    $context.authorizer.integrationLatency

授權方整合延遲 (以毫秒為單位)。


                    $context.authorizer.integrationStatus

從 Lambda 授權方傳回的狀態碼。


                    $context.authorizer.latency

授權方延遲 (以毫秒為單位)。


                    $context.authorizer.principalId


                    $context.authorizer.
                    
                     property


                    $context.customDomain.routingRuleIdMatched

傳入請求相符的路由規則。適用於用戶端使用自訂網域名稱來存取 API 時。如需詳細資訊，請參閱將 API 階段連線至 REST APIs 自訂網域名稱的路由規則。


                    $context.deploymentId

API 部署的 ID。


                    $context.domainName


                    $context.domainPrefix


                    $context.endpointType

API 的端點類型。


                    $context.error.message


                    $context.error.messageString


                    $context.error.message

的引用值，即


                    "$context.error.message"

。


                    $context.error.responseType


                    $context.error.validationErrorString


                    $context.extendedRequestId

API Gateway 產生和指派給 API 請求的延伸 ID。延伸請求 ID 包含有助於偵錯和疑難排解的資訊。


                    $context.httpMethod


                    $context.identity.accountId


                    $context.identity.apiKey


                    $context.identity.apiKeyId

與需要 API 金鑰之 API 請求相關聯的 API 金鑰 ID。


                    $context.identity.caller


                    $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 驗證提供者的詳細資訊，請參閱《 Amazon Cognito 開發人員指南》中的 使用聯合身分 。


                    $context.identity.cognitoAuthenticationType

提出請求的發起人的 Amazon Cognito 驗證類型。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。可能的值包括用於已驗證身分的 authenticated 和未經驗證身分的 unauthenticated 。


                    $context.identity.cognitoIdentityId


                    $context.identity.cognitoIdentityPoolId


                    $context.identity.principalOrgId


                    $context.identity.sourceIp


                    $context.identity.clientCert.clientCertPem


                    $context.identity.clientCert.subjectDN


                    $context.identity.clientCert.issuerDN


                    $context.identity.clientCert.serialNumber


                    $context.identity.clientCert.validity.notBefore


                    $context.identity.clientCert.validity.notAfter


                    $context.integration.integrationStatus

對於 Lambda 代理整合，從傳回的狀態碼 AWS Lambda，而不是從後端 Lambda 函數程式碼傳回的狀態碼。


                    $context.integration.latency

整合延遲 (以毫秒為單位)。等同於


                    $context.integrationLatency

。


                    $context.integration.requestId

AWS 端點的請求 ID。等同於


                    $context.awsEndpointRequestId

。


                    $context.integration.status

從整合傳回的狀態碼。對於 Lambda 代理整合而言，這是您的 Lambda 函數程式碼傳回的狀態碼。


                    $context.integrationLatency

整合延遲 (以毫秒為單位)。


                    $context.integrationStatus

對於 Lambda 代理整合，此參數代表從傳回的狀態碼 AWS Lambda，而不是從後端 Lambda 函數程式碼傳回的狀態碼。


                    $context.isCanaryRequest


                    $context.path

請求路徑。例如，對於


                    https://
                    
                     {
                    
                    rest-api-id}.execute-api.
                    
                     {
                    
                    region}.amazonaws.com/
                    
                     {
                    
                    stage}/root/child

的非代理請求 URL，


                    $context.path

值是


                    /
                    
                     {
                    
                    stage}/root/child

。


                    $context.protocol

請求通訊協定，例如


                    HTTP/1.1

。

注意

API Gateway API 可以接受 HTTP/2 請求，但 API Gateway 會使用 HTTP/1.1 將請求傳送至後端整合。因此，即使用戶端傳送使用 HTTP/2 的請求，請求通訊協定也會記錄為 HTTP/1.1。


                    $context.requestId


                    $context.requestOverride.header.
                    
                     header_name


                    $context.requestOverride.path.
                    
                     path_name


                    $context.requestOverride.querystring.
                    
                     querystring_name


                    $context.responseLatency

回應延遲 (以毫秒為單位)。


                    $context.responseLength

回應承載長度 (以位元組為單位)。


                    $context.responseOverride.header.
                    
                     header_name

回應標題會覆寫。如果此參數已經定義，它包含要傳回的標頭 (而不是在 Integration Response (整合回應) 窗格中定義為 Default mapping (預設映射) 的 Response header (回應標頭) )。如需詳細資訊，請參閱覆寫 API Gateway 中 REST APIs的 API 請求和回應參數和狀態碼。


                    $context.responseOverride.status

回應狀態碼會覆寫。如果此參數已經定義，它包含要傳回的狀態碼 (而不是在 Integration Response (整合回應) 窗格中定義為 Default mapping (預設映射) 的 Method response status (方法回應狀態) )。如需詳細資訊，請參閱覆寫 API Gateway 中 REST APIs的 API 請求和回應參數和狀態碼。


                    $context.requestTime

CLF

格式化請求時間 (


                    dd/MMM/yyyy:HH:mm:ss
              +-hhmm

)。


                    $context.requestTimeEpoch

Epoch

格式化的要求時間，以毫秒為單位。


                    $context.resourceId


                    $context.resourcePath


                    $context.stage


                    $context.status

方法回應狀態。


                    $context.waf.error

從傳回的錯誤訊息 AWS WAF。


                    $context.waf.latency

以毫秒為單位的 AWS WAF 延遲。


                    $context.waf.status

從傳回的狀態碼 AWS WAF。


                    $context.xrayTraceId


                    $context.wafResponseCode

API 擁有者 AWS 的帳戶 ID。

API Gateway 指派給您 API 的識別碼。

成功驗證方法發起人之後，從 Amazon Cognito 使用者集區傳回之宣告的屬性。如需詳細資訊，請參閱使用 Amazon Cognito 使用者集區做為授權方，藉以控制對 REST API 的存取。

注意

呼叫 $context.authorizer.claims 會傳回 null。

與用戶端所傳送並從 API Gateway Lambda 授權方 (先前稱作自訂授權方) 所傳回之字符相關聯的主要使用者身分。如需詳細資訊，請參閱使用 API Gateway Lambda 授權方。

API Gateway Lambda 授權方函數所傳回 context 映射之指定索引鍵/值組的字串化值。例如，如果授權方傳回下列 context 映射：


"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
            呼叫 $context.authorizer.key 會傳回 "value" 字串，呼叫 $context.authorizer.numKey 會傳回 "1" 字串，而呼叫 $context.authorizer.boolKey 會傳回 "true" 字串。
            對於屬性，唯一支援的特殊字元是底線 (_) 字元。
            如需詳細資訊，請參閱使用 API Gateway Lambda 授權方。

用來調用 API 的完整網域名稱。這應該與傳入的 Host 標頭相同。

$context.domainName 的第一個標籤。

包含 API Gateway 錯誤訊息的字串。此變數只能用於 Velocity 範本語言引擎無法處理的 GatewayResponse 本文映射範本及存取記錄中的簡單變數替換。如需詳細資訊，請參閱使用 CloudWatch 指標監控 WebSocket API 執行及設定閘道回應以自訂錯誤回應。

GatewayResponse 的類型。此變數只能用於 Velocity 範本語言引擎無法處理的 GatewayResponse 本文映射範本及存取記錄中的簡單變數替換。如需詳細資訊，請參閱使用 CloudWatch 指標監控 WebSocket API 執行及設定閘道回應以自訂錯誤回應。

字串，其中包含詳細的驗證錯誤訊息。

使用的 HTTP 方法。有效值包含： DELETE 、 GET 、 HEAD 、 OPTIONS 、 PATCH 、 POST 和 PUT 。

與請求相關聯的 AWS 帳戶 ID。

對於需要 API 金鑰的 API 方法，此變數是與方法請求相關聯的 API 金鑰。對於不需要 API 金鑰的方法，此變數為 null。如需詳細資訊，請參閱 API Gateway 中 REST API 的用量計畫和 API 金鑰。

已簽署請求之發起人的主體識別符。支援使用 IAM 授權的資源。

提出請求的發起人的 Amazon Cognito 身分 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。

提出請求的發起人的 Amazon Cognito 身分集區 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。

AWS 組織 ID 。

對 API Gateway 端點提出請求之即時 TCP 連線的來源 IP 位址。

用戶端在交互 TLS 驗證期間所呈現的 PEM 編碼用戶端憑證。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。

用戶端提供之憑證主體的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。

用戶端提供之憑證發行者的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。

憑證的序號。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。

憑證無效之前的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。

憑證無效之後的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。只有在交互 TLS 驗證失敗時才會顯示在存取記錄檔中。

如果請求導向 Canary，則傳回 true ；如果請求未導向 Canary，則傳回 false 。只會在啟用 Canary 時顯示。

請求的 ID。用戶端可以覆寫此請求 ID。使用 $context.extendedRequestId 即可取得 API Gateway 產生的唯一請求 ID。

請求標題會覆寫。如果此參數已經定義，它包含要使用的標頭 (而不是在 Integration Request (整合請求) 窗格中定義的 HTTP Headers (HTTP 標頭) )。如需詳細資訊，請參閱覆寫 API Gateway 中 REST APIs的 API 請求和回應參數和狀態碼。

請求路徑會覆寫。如果此參數已經定義，它包含要使用的請求路徑 (而不是在 Integration Request (整合請求) 窗格中定義的 URL Path Parameters (URL 路徑參數) )。如需詳細資訊，請參閱覆寫 API Gateway 中 REST APIs的 API 請求和回應參數和狀態碼。

請求查詢字串會覆寫。如果此參數已經定義，它包含要使用的請求查詢字串 (而不是在 Integration Request (整合請求) 窗格中定義的 URL Query String (URL 查詢字串) )。如需詳細資訊，請參閱覆寫 API Gateway 中 REST APIs的 API 請求和回應參數和狀態碼。

API Gateway 指派給您的資源的識別碼。

您資源的路徑。例如，對於非代理請求 URI https:// { rest-api-id}.execute-api. { region}.amazonaws.com/ { stage}/root/child ， $context.resourcePath 值是 /root/child 。如需詳細資訊，請參閱教學：建立具有 HTTP 非代理整合的 REST API 。

API 請求的部署階段 (例如， Beta 或 Prod )。

X-Ray 追蹤的追蹤 ID。如需詳細資訊，請參閱 AWS X-Ray 使用 API Gateway REST APIs設定。

從 AWS WAF 收到的回應： WAF_ALLOW 或 WAF_BLOCK 。若該階段與 web ACL 不相關聯，將不會設定此值。如需詳細資訊，請參閱使用 AWS WAF 來保護 API Gateway APIs 中的 REST API 。