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

# 用於 API Gateway 資料轉換的變數
<a name="api-gateway-mapping-template-reference"></a>

建立參數映射時，您可以使用內容變數作為資料來源。建立映射範本轉換時，您可以在您使用 [Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 編寫的指令碼中使用內容變數、輸入和 util 變數。如需使用這些參考變數的映射範本範例，請參閱 [使用變數進行 API Gateway 映射範本轉換的範例](api-gateway-mapping-variable-examples.md)。

如需存取記錄的參考變數清單，請參閱 [API Gateway 存取記錄的變數](api-gateway-variables-for-access-logging.md)。

## 資料轉換的內容變數
<a name="context-variable-reference"></a>

您可以使用下列區分大小寫的 `$context` 變數進行資料轉換。


| 參數 | Description | 
| --- | --- | 
| \$1context.accountId |  API 擁有者 AWS 的帳戶 ID。  | 
| \$1context.apiId |  API Gateway 指派給您 API 的識別碼。  | 
| \$1context.authorizer.claims.property |  成功驗證方法發起人之後，從 Amazon Cognito 使用者集區傳回之宣告的屬性。如需詳細資訊，請參閱 [使用 Amazon Cognito 使用者集區做為授權方，藉以控制對 REST API 的存取](apigateway-integrate-with-cognito.md)。  呼叫 `$context.authorizer.claims` 會傳回 null。   | 
| \$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.awsEndpointRequestId |   AWS 端點的請求 ID。  | 
| \$1context.deploymentId | API 部署的 ID。 | 
| \$1context.domainName |  用來調用 API 的完整網域名稱。這應該與傳入的 `Host` 標頭相同。  | 
| \$1context.domainPrefix |  `$context.domainName` 的第一個標籤。  | 
| \$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.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.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.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)。  | 

## 輸入變數
<a name="input-variable-reference"></a>

您可以使用下列區分大小寫的 `$input` 變數來參考方法請求承載和方法請求參數。可使用以下函數：


| 變數和函數 | 描述 | 
| --- | --- | 
| \$1input.body |  傳回原始請求承載做為字串。您可以使用 `$input.body` 保留整個浮點數，例如 `10.00`。 | 
| \$1input.json(x) | 此函數會評估 JSONPath 表達式，並傳回結果作為 JSON 字串。 例如，`$input.json('$.pets')` 會傳回代表 `pets` 結構的 JSON 字串。 如需 JSONPath 的詳細資訊，請參閱 [JSONPath](https://goessner.net/articles/JsonPath/) 或[適用於 Java 的 JSONPath](https://github.com/json-path/JsonPath)。 | 
| \$1input.params() |  傳回所有請求參數的映射。我們建議您使用 `$util.escapeJavaScript` 清理結果，以避免潛在的注入攻擊。為了完全控制請求清理，請使用沒有模板的代理整合，並處理整合中的請求清理。 | 
| \$1input.params(x) | 從路徑、查詢字串或標頭值 (以此順序搜尋) 傳回方法請求參數值，而參數名稱字串為 `x`。我們建議您使 `$util.escapeJavaScript` 用清理參數，以避免潛在的注入攻擊。為了完全控制參數清理，請使用沒有模板的代理整合，並處理整合中的請求清理。 | 
| \$1input.path(x) | 採用 JSONPath 表達式字串 (`x`)，並傳回結果的 JSON 物件呈現。這可讓您存取和運用 [Apache Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 中原生承載的元素。 例如，如果表達式 `$input.path('$.pets')` 傳回如下物件： <pre>[<br />  { <br />    "id": 1, <br />    "type": "dog", <br />    "price": 249.99 <br />  }, <br />  { <br />    "id": 2, <br />    "type": "cat", <br />    "price": 124.99 <br />  }, <br />  { <br />    "id": 3, <br />    "type": "fish", <br />    "price": 0.99 <br />  } <br />]</pre> `$input.path('$.pets').size()` 會傳回 `"3"`。 如需 JSONPath 的詳細資訊，請參閱 [JSONPath](https://goessner.net/articles/JsonPath/) 或[適用於 Java 的 JSONPath](https://github.com/json-path/JsonPath)。 | 

## 階段變數
<a name="stagevariables-template-reference"></a>

您可以使用下列階段變數作為方法整合中 ARN 和 URL 的預留位置。如需詳細資訊，請參閱[在 API Gateway 中使用 REST API 的階段變數](stage-variables.md)。


| 語法 | Description | 
| --- | --- | 
| \$1stageVariables.variable\$1name、\$1stageVariables['variable\$1name'] 或 \$1\$1stageVariables['variable\$1name']\$1  |  *variable\$1name* 代表階段變數名稱。  | 

## Util 變數
<a name="util-template-reference"></a>

您可以使用下列區分大小寫的 `$util` 變數，針對映射範本使用公用程式函數。除非特別指定，否則預設字元集為 UTF-8。


| 函數 | 描述 | 
| --- | --- | 
| \$1util.escapeJavaScript() |  使用 JavaScript 字串規則來逸出字串中的字元。  此函數會將任何一般單引號 (`'`) 轉換為逸出單引號 (`\'`)。不過，逸出單引號不適用於 JSON。因此，將此函數的輸出用於 JSON 屬性時，您必須將任何逸出單引號 (`\'`) 轉換為一般單引號 (`'`)。下列範例顯示這種情況： <pre> "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"</pre>   | 
| \$1util.parseJson() |   採用「字串化」JSON，並傳回結果的物件呈現。您可以使用此函數的結果，來存取和運用 Apache Velocity 範本語言 (VTL) 中原生承載的元素。例如，如果您有下列承載： <pre>{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}</pre>  並使用下列映射範本  <pre>#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))<br />{<br />   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]<br />}<br /></pre> 您將會收到下列輸出： <pre>{<br />   "errorMessageObjKey2ArrVal" : 1<br />}<br /></pre>  | 
| \$1util.urlEncode() | 將字串轉換為 "application/x-www-form-urlencoded" 格式。 | 
| \$1util.urlDecode() | 解碼 "application/x-www-form-urlencoded" 字串。 | 
| \$1util.base64Encode() | 將資料編碼為 base64 編碼字串。 | 
| \$1util.base64Decode() | 解碼 base64 編碼字串中的資料。 |