# API Gateway での WebSocket API のデータ変換 API Gateway では、API のメソッドリクエストは、バックエンドで必要となる、該当する統合リクエストペイロードとは異なる形式のペイロードを受け取ることができます。同様に、バックエンドは、フロントエンドで予期されるメソッドレスポンスペイロードとは異なる統合レスポンスペイロードを返す場合があります。 API Gateway では、マッピングテンプレート変換を使用して、ペイロードをメソッドリクエストから該当する統合リクエストにマッピングしたり、統合レスポンスから該当するメソッドレスポンスにマッピングしたりできます。マッピングテンプレートを作成し、テンプレート選択式を指定して、必要なデータ変換の実行に使用するテンプレートを決定します。 データマッピングを使用して、[ルートリクエスト](api-gateway-basic-concept.md#apigateway-definition-route-request)からバックエンド統合にデータをマッピングできます。詳細については、「[API Gateway で WebSocket API のデータマッピングを設定する](websocket-api-data-mapping.md)」を参照してください。 ## テンプレートとモデルのマッピング *マッピングテンプレート*は、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で表現されるスクリプトであり、[JSONPath 式](https://goessner.net/articles/JsonPath/)を使用してペイロードに適用されます。API Gateway マッピングテンプレートの詳細については、「[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md)」を参照してください。 ペイロードでは、[JSON スキーマのドラフト 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) に基づく*データモデル*を使用できます。マッピングテンプレートを作成するためにモデルを定義する必要はありません。ただし、API Gateway では指定されたモデルに基づいてテンプレート設計図が生成されるため、モデルはテンプレートの作成に役立ちます。API Gateway モデルの詳細については、「[REST API のデータモデル](models-mappings-models.md)」を参照してください。 ## テンプレート選択式 マッピングテンプレートを使用してペイロードを変換するには、[統合リクエスト](apigateway-websocket-api-integration-requests.md)または[統合レスポンス](apigateway-websocket-api-integration-responses.md)で WebSocket API テンプレート選択式を指定します。この式の評価により、(入力テンプレートを介して) リクエストボディを統合リクエストボディに変換するか、(出力テンプレートを介して) 統合レスポンスボディをルートレスポンスボディに変換するために使用される入力または出力テンプレート (存在する場合) が決定されます。 `Integration.TemplateSelectionExpression` は、`${request.body.jsonPath}` および静的な値をサポートします。 `IntegrationResponse.TemplateSelectionExpression` は、`${request.body.jsonPath}`、`${integration.response.statuscode}`、`${integration.response.header.headerName}`、`${integration.response.multivalueheader.headerName}` および静的な値をサポートします。 ## 統合レスポンスの選択式 WebSocket API に対して[統合レスポンス](apigateway-websocket-api-integration-responses.md)を設定するときは、オプションで統合レスポンスの選択式を指定できます。この式により、統合が返されるときに選択する `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` が決定されます。現在、この式の値は以下に定義するように、API Gateway によって制限されています。この式は*非プロキシ統合*に対してのみ適用されることに注意してください。プロキシ統合は、モデル化または変更なしに、単純にレスポンスペイロードを呼び出し元に渡すだけです。 上記に示した他の選択式とは異なり、この式は*パターンマッチング*形式を現在サポートしています。式はスラッシュで囲む必要があります。 現在、値は `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)` に応じて固定されています。 + Lambda ベースの統合の場合は、`$integration.response.body.errorMessage` です。 + `HTTP` および `MOCK` 統合の場合、その値は `$integration.response.statuscode` です。 + `HTTP_PROXY` と `AWS_PROXY` の場合、式は利用されません。これは、呼び出し元へのペイロードのパススルーをリクエストしているためです。 # API Gateway で WebSocket API のデータマッピングを設定する *データマッピング*を使用すると、[ルートリクエスト](api-gateway-basic-concept.md#apigateway-definition-route-request)からバックエンド統合にデータをマッピングできます。 **注記** WebSocket API のデータマッピングは、 ではサポートされていませんAWS マネジメントコンソール データマッピングを設定するには、AWS CLI、AWS CloudFormation、または SDK を使用する必要があります。 **Topics** + [ルートリクエストデータを統合リクエストパラメータにマッピングする](#websocket-mapping-request-parameters) + [例](#websocket-data-mapping-examples) ## ルートリクエストデータを統合リクエストパラメータにマッピングする 統合リクエストパラメータは、定義されたルートリクエストパラメータ、リクエストボディ、[`context`](api-gateway-mapping-template-reference.md#context-variable-reference) または [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) 変数、静的値からマッピングできます。 次の表は、統合リクエストのデータマッピング式を示しています。表で、*`PARAM_NAME`* は、特定のパラメータ型のルートリクエストパラメータの名前です。正規表現パターン `'^[a-zA-Z0-9._$-]+$]'` に一致する必要があります。*JSONPath\$1EXPRESSION* はリクエストボディの JSON フィールドの JSONPath 式です。 | マッピングされたデータソース | マッピング式 | | --- | --- | | リクエストクエリ文字列 (\$1connect ルートでのみサポート) | route.request.querystring.PARAM\$1NAME | | リクエストヘッダー (\$1connect ルートでのみサポート) | route.request.header.PARAM\$1NAME | | 複数値のリクエストクエリ文字列 (\$1connect ルートでのみサポート) | route.request.multivaluequerystring.PARAM\$1NAME | | 複数値のリクエストヘッダー (\$1connect ルートでのみサポート) | route.request.multivalueheader.PARAM\$1NAME | | リクエストボディ | route.request.body.JSONPath\$1EXPRESSION | | ステージ変数 | stageVariables.VARIABLE\$1NAME | | コンテキスト変数 | [サポートされるコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)の 1 つである必要がある context.VARIABLE\$1NAME。 | | 静的な値 | 'STATIC\$1VALUE'。STATIC\$1VALUE はリテラル文字列であり、単一引用符で囲む必要があります。 | データマッピングを作成するときは、AWS CLI を使用して、AWS CLI の文字列でリテラルを使用するための正しい形式に従ってください。詳細については、「*AWS Command Line Interface ユーザーガイド*」の「[AWS CLI で文字列に引用符とリテラルを使用する](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html)」を参照してください。 ## 例 以下の AWS CLI の例では、データマッピングを設定しています。CloudFormation テンプレートの例については、「[samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip)」を参照してください。 ### クライアントの connectionId を統合リクエストのヘッダーにマッピングする 次の [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) コマンドは、クライアントの `connectionId` をバックエンド統合へのリクエストの `connectionId` ヘッダーにマッピングします。 ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### クエリ文字列パラメータを統合リクエストのヘッダーにマッピングする 次の例では、`authToken` クエリ文字列パラメータを統合リクエストの `authToken` ヘッダーにマッピングします。 1. 次の [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) コマンドを使用して、`authToken` クエリ文字列パラメータをルートのリクエストパラメータに追加します。 ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. 次の [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) コマンドを使用して、クエリ文字列パラメータをバックエンド統合へのリクエストの `authToken` ヘッダーにマッピングします。 ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (オプション) 必要に応じて、次の [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html) を使用して、ルートのリクエストパラメータから `authToken` クエリ文字列パラメータを削除します。 ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # API Gateway の WebSocket API マッピングテンプレートのリファレンス このセクションでは、API Gateway の WebSocket API で現在サポートされている一連の変数の概要を示します。 | パラメータ | 説明 | | --- | --- | | \$1context.connectionId | クライアントへのコールバックを行うために使用できる接続の一意の ID。 | | \$1context.connectedAt | [エポック](https://en.wikipedia.org/wiki/Unix_time)形式の接続時間。 | | \$1context.domainName | WebSocket API のドメイン名。これは、(ハードコーディングされた値の代わりに) クライアントへのコールバックを行うために使用できます。 | | \$1context.eventType | イベントタイプ: (`CONNECT`、`MESSAGE`、または `DISCONNECT`)。 | | \$1context.messageId | メッセージの一意のサーバー側 ID。`$context.eventType` が `MESSAGE` である場合のみ利用できます。 | | \$1context.routeKey | 選択されたルートキー。 | | \$1context.requestId | `$context.extendedRequestId` と同じ | | \$1context.extendedRequestId | 自動生成された API コールの ID。デバッグとトラブルシューティングにさらに役立つ情報が含まれています。 | | \$1context.apiId | API Gateway が API に割り当てる識別子。 | | \$1context.authorizer.principalId | クライアントにより送信され、API Gateway Lambda オーソライザー (以前のカスタムオーソライザー) の Lambda 関数から返されたトークンと関連付けられたプリンシパルユーザー ID。 | | \$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.error.messageString | \$1context.error.message を引用符で囲んだ値、つまり "\$1context.error.message"。 | | \$1context.error.validationErrorString | 詳細な検証エラーメッセージを含む文字列。 | | \$1context.identity.accountId | リクエストに関連付けられた AWS アカウント ID です。 | | \$1context.identity.apiKey | キー対応 API リクエストに関連付けられた API 所有者キー。 | | \$1context.identity.apiKeyId | キー対応 API リクエストに関連付けられた API キー ID。 | | \$1context.identity.caller | リクエストを実行している発信者のプリンシパル ID です。 | | \$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.sourceIp | API Gateway エンドポイントへのリクエストを実行する即時 TCP 接続のソース IP アドレス。 | | \$1context.identity.user | リクエストを実行しているユーザーのプリンシパル ID です。 | | \$1context.identity.userAgent | API 発信者のユーザーエージェントです。 | | \$1context.identity.userArn | 認証後に識別された有効ユーザーの Amazon リソースネーム (ARN) です。 | | \$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.stage | API コールの開発ステージ (Beta、Prod など)。 | | \$1context.status | レスポンスステータス。 | | \$1input.body | 文字列として raw ペイロードを返します。 | | \$1input.json(x) | この関数は、JSONPath の式を評価し、結果を JSON 文字列で返します。 たとえば `$input.json('$.pets')` は、ペットの構造を表す JSON 文字列を返します。 JSONPath の詳細については、[JSONPath](https://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/json-path/JsonPath) を参照してください。 | | \$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').count()` は `"3"` を返します。 JSONPath の詳細については、[JSONPath](http://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/jayway/JsonPath) を参照してください。 | | \$1stageVariables. | ** はステージ変数名を表します。 | | \$1stageVariables[''] | ** は任意のステージ変数名を表します。 | | \$1\$1stageVariables['']\$1 | ** は任意のステージ変数名を表します。 | | \$1util.escapeJavaScript() | JavaScript 文字列ルールを使用して文字列内の文字をエスケープします。 この関数は、通常の一重引用符 (`'`) をエスケープした一重引用符 (`\'`) に変換します。ただし、エスケープした一重引用符は JSON で有効ではありません。したがって、この関数からの出力を JSON のプロパティで使用する場合、エスケープした一重引用符 (`\'`) を通常の一重引用符 (`'`) に戻す必要があります。これを次の例で示します: 
 $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 エンコードされた文字列からデータをデコードします。 |