API リクエストとレスポンスの変換 - Amazon API Gateway

API リクエストとレスポンスの変換

バックエンド統合に到達する前に、クライアントからの API リクエストを変更できます。API Gateway がクライアントに応答を返す前に、統合からレスポンスを変更することもできます。パラメータマッピングを使用して、HTTP API の API リクエストとレスポンスを変更します。パラメーターマッピングを使用するには、変更する API リクエストまたはレスポンスパラメーターを指定し、それらのパラメーターを変更する方法を指定します。

API リクエストの変換

リクエストパラメーターを使用して、バックエンド統合に到達する前にリクエストを変更します。ヘッダー、クエリ文字列、リクエストパス、またはリクエスト本文を変更できます。

リクエストパラメータは、キーと値のマップです。キーは、変更するリクエストパラメーターの場所とその変更方法を識別します。値は、パラメータの新しいデータを指定します。

次の表に、サポートされているキーを示します。

パラメータのマッピングキー
タイプ 構文
Header append|overwrite|remove:header.headername
クエリ文字列 append|overwrite|remove:querystring.querystring-name
パス overwrite:path

次の表に、パラメータにマップできるサポートされている値を示します。

パラメータのマッピング値をリクエストする
タイプ 構文 注意
ヘッダー値 $request.header.name ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「予約済みヘッダー」を参照してください。
クエリ文字列値 $request.querystring.name クエリ文字列名では大文字と小文字が区別されます。API Gateway は複数の値をコンマで結合します (例: "querystring1" "Value1,Value2")。
リクエストボディ $request.body.name JSON path 式。再帰下降 ($request.body..name)) およびフィルタ式 (?(expression)) はサポートされていません。
注記

JSON パスを指定すると、API Gateway はリクエスト本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、$request.body を指定します。

リクエストパス $request.path ステージ名を含まないリクエストパス。
パスパラメータ $request.path.name リクエストのパスパラメータの値。例えば、ルートが /pets/{petId} の場合は、$request.path.petId を使用してリクエストのパラメータpetIdをマッピングできます。
コンテキスト変数 $context.variableName コンテキスト変数の値 。
ステージ変数 $stageVariables.variableName ステージ変数の値。
静的な値 文字列 定数値。

API レスポンスの変換

レスポンスをクライアントに返す前に、レスポンスパラメーターを使用して HTTP レスポンスをバックエンド統合から変換します。API Gateway がクライアントにレスポンスを返す前に、ヘッダーまたはステータスコードを変更できます。

統合によって返されるステータスコードごとに、レスポンスパラメーターを構成します。レスポンスパラメータは、キーと値のマップです。キーは、変更するリクエストパラメーターの場所とその変更方法を識別します。値は、パラメータの新しいデータを指定します。

次の表に、サポートされているキーを示します。

応答パラメータのマッピングキー
タイプ 構文
Header append|overwrite|remove:header.headername
ステータスコード overwrite:statuscode

次の表に、サポートされている、パラメータにマップできる値を示します。

レスポンスパラメータのマッピング値
タイプ 構文 注意
ヘッダー値 $request.header.name ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「予約済みヘッダー」を参照してください。
レスポンス本文 $response.body。名前 JSON path 式。再帰下降 ($response.body..name) およびフィルター式 (?(expression)) はサポートされていません。
注記

JSON パスを指定すると、API Gateway はレスポンス本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、$response.body を指定します。

コンテキスト変数 $context.variableName サポートされているコンテキスト変数の値。
ステージ変数 $stageVariables.variableName ステージ変数の値。
静的な値 文字列 定数値。

予約済みヘッダー

次のヘッダーは予約されています。これらのヘッダーには、要求またはレスポンスマッピングを構成できません。

  • access-control-*

  • apigw-*

  • Authorization

  • Connection

  • Content-Encoding

  • Content-Length

  • Content-Location

  • 転送済み

  • Keep-Alive

  • Origin

  • Proxy-Authenticate

  • Proxy-Authorization

  • TE

  • トレーラー

  • Transfer-Encoding

  • Upgrade

  • x-amz-*

  • x-amzn-*

  • X-Forwarded-For

  • X-Forwarded-Host

  • X-Forwarded-Proto

  • Via

以下の AWS CLI の例では、データマッピングを設定しています。たとえば AWS CloudFormation テンプレートについては、「 GitHub 」を参照してください。

API リクエストへのヘッダーの追加

次の例では、バックエンド統合に到達する前に API リクエストにheader1という名前のヘッダーを追加します。API Gateway は、ヘッダーにリクエスト ID を設定します。

aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters '{ "append:header.header1": "$context.requestId" }'

リクエストヘッダーの名前を変更する

次の例では、リクエストヘッダーの名前をheader1からheader2に変更します 。

aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}' }

統合からのレスポンスの変更

次の例では、統合のレスポンスパラメータを設定します。インテグレーションが 500 ステータスコードを返すと、API Gateway はステータスコードを 403 に変更し、応答に header1 1 を追加します。統合によって 404 ステータスコードが返されると、API Gateway は応答にヘッダーerrorを追加します。

aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }

構成されたパラメータマッピングの削除

次のコマンド例では、以前に設定されたリクエストパラメータappend:header.header1を削除します。また、200 ステータスコードに対して以前に構成されたレスポンスパラメータも削除されます。

aws apigatewayv2 update-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters {"append:header.header1" : ""} \ --response-parameters {"200" : {}}