# API Gateway のデータ変換の変数 パラメータマッピングを作成する場合、データソースとしてコンテキスト変数を使用できます。マッピングテンプレート変換を作成する場合、[Velocity Template Language (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)」を参照してください。 ## データ変換のコンテキスト変数 データ変換には、次の大文字と小文字が区別される `$context` 変数を使用できます。 | パラメータ | 説明 | | --- | --- | | \$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 オーソライザー (以前のカスタムオーソライザー) から返されたトークンと関連付けられたプリンシパルユーザー ID。詳細については、「[API Gateway Lambda オーソライザーを使用する](apigateway-use-lambda-authorizer.md)」を参照してください。 | | \$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"` 文字列が返されます。 *プロパティ* でサポートされる特殊文字は、アンダースコア `(_)` 文字のみです。 詳細については、「[API Gateway Lambda オーソライザーを使用する](apigateway-use-lambda-authorizer.md)」を参照してください。 | | \$1context.awsEndpointRequestId | AWS エンドポイントのリクエスト ID | | \$1context.deploymentId | API デプロイの ID。 | | \$1context.domainName | API の呼び出しに使用された完全ドメイン名。これは、受信 `Host` ヘッダーと同じである必要があります。 | | \$1context.domainPrefix | `$context.domainName` の 1 つ目のラベル。 | | \$1context.error.message | API Gateway のエラーメッセージを含む文字列。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、[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) の [type](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、[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 | リクエストに署名した発信者のプリンシパル ID。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 開発者ガイド」の「[フェデレーティッド ID の使用](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 プール 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 リソースネーム (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 を上書きできます。API Gateway が生成する一意のリクエスト ID に `$context.extendedRequestId` を使用します。 | | \$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 Parameters (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 | [エポック](https://en.wikipedia.org/wiki/Unix_time)形式のリクエスト時間 (ミリ秒単位)。 | | \$1context.resourceId | API Gateway がリソースに割り当てる識別子です。 | | \$1context.resourcePath | リソースへのパスです。たとえば、`https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` の非プロキシリクエスト URI の場合、`$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`。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「[AWS WAF を使用して API Gateway の REST API を保護する](apigateway-control-access-aws-waf.md)」を参照してください。 | | \$1context.webaclArn | リクエストを許可するかブロックするかを決定するために使用されるウェブ ACL の完全な ARN。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「[AWS WAF を使用して API Gateway の REST API を保護する](apigateway-control-access-aws-waf.md)」を参照してください。 | ## 入力変数 次の大文字と小文字が区別される `$input` 変数を使用して、メソッドリクエストペイロードとメソッドリクエストパラメータを参照できます。以下の機能を使用できます。 | 変数と関数 | 説明 | | --- | --- | | \$1input.body | 文字列として raw リクエストペイロードを返します。`$input.body` を使用して、浮動小数点数全体 (`10.00` など) を保持できます。 | | \$1input.json(x) | この関数は、JSONPath の式を評価し、結果を JSON 文字列で返します。 たとえば `$input.json('$.pets')` は、`pets` 構造を表す JSON 文字列を返します。 JSONPath の詳細については、[JSONPath](https://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/json-path/JsonPath) を参照してください。 | | \$1input.params() | すべてのリクエストパラメータのマップを返します。インジェクション攻撃の可能性を避けるため、`$util.escapeJavaScript` を使用して結果をサニタイズすることをお勧めします。リクエストのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。 | | \$1input.params(x) | パラメータ名文字列 `x` が指定された場合に、パス、クエリ文字列、またはヘッダー値から (この順番で検索される) メソッドリクエストパラメータの値を返します。インジェクション攻撃の可能性を避けるため、`$util.escapeJavaScript` を使用してパラメータをサニタイズすることをお勧めします。パラメータのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。 | | \$1input.path(x) | JSONPath 式文字列 (`x`) を受け取り、結果の JSON オブジェクト表現を返します。これにより、[Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) でペイロード要素にネイティブにアクセスして操作できます。 たとえば、式 `$input.path('$.pets')` が次のようにオブジェクトを返すとします。 
[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]
`$input.path('$.pets').size()` は を返します。`"3"` JSONPath の詳細については、[JSONPath](https://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/json-path/JsonPath) を参照してください。 | ## ステージ変数 メソッド統合では、次のステージ変数を ARN と URL のプレースホルダーとして使用できます。詳細については、「[API Gateway で REST API のステージ変数を使用する](stage-variables.md)」を参照してください。 | 構文 | 説明 | | --- | --- | | \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'], または \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* はステージ変数名を表します。 | ## Util 変数 マッピングテンプレートのユーティリティ関数を使用するには、次の大文字と小文字が区別される `$util` 変数を使用できます。別に指定されていない限り、デフォルトの文字は UTF-8 に設定されます。 | 関数 | 説明 | | --- | --- | | \$1util.escapeJavaScript() | JavaScript 文字列ルールを使用して文字列内の文字をエスケープします。 この関数は、通常の一重引用符 (`'`) をエスケープした一重引用符 (`\'`) に変換します。ただし、エスケープした一重引用符は JSON で有効ではありません。したがって、この関数からの出力を JSON のプロパティで使用する場合、エスケープした一重引用符 (`\'`) を通常の一重引用符 (`'`) に戻す必要があります。これを次の例で示します: 
 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
| | \$1util.parseJson() | "stringified" JSON を受け取り、結果のオブジェクト表現を返します。この関数の結果を使用して、Apache Velocity Template Language (VTL) でペイロード要素にネイティブにアクセスしてこれらの要素を操作できるようになります。たとえば、次のペイロードがあるとします。 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
さらに、次のマッピングテンプレートを使用するとします。 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
この場合、次の出力が返されます。 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | 文字列を「application/x-www-form-urlencoded」形式に変換します。 | | \$1util.urlDecode() | 「application/x-www-form-urlencoded」文字列をデコードします。 | | \$1util.base64Encode() | データを base64 エンコードされた文字列にエンコードします。 | | \$1util.base64Decode() | base64 エンコードされた文字列からデータをデコードします。 |