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

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

API リクエストの変換

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

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

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

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

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

パラメータのマッピング値をリクエストする
タイプ	構文	コメント
ヘッダー値	$request.header.name または ${request.header.name}	ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「予約済みヘッダー」を参照してください。
クエリ文字列値	$request.querystring.name または ${request.querystring.name}	クエリ文字列名では大文字と小文字が区別されます。API Gateway は複数の値をコンマで結合します (例: "querystring1" "Value1,Value2")。
リクエストボディ	$request.body.name または ${request.body.name}	JSON path 式。再帰下降 ($request.body..name)) およびフィルタ式 (?(expression)) はサポートされていません。 注記 JSON パスを指定すると、API Gateway はリクエスト本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、$request.body を指定します。
リクエストパス	$request.path または ${request.path}	ステージ名を含まないリクエストパス。
パスパラメータ	$request.path.name または ${request.path.name}	リクエストのパスパラメータの値。例えば、ルートが /pets/{petId} の場合は、petId を使用してリクエストのパラメータ$request.path.petIdをマッピングできます。
コンテキスト変数	$context.variableName または ${context.variableName}	コンテキスト変数の値 。 注記 特殊文字の . と _ のみがサポートされています。
ステージ変数	$stageVariables.variableName または ${stageVariables.variableName}	ステージ変数の値。
静的な値	文字列	定数値。

注記

選択式で複数の変数を使用するには、変数を角かっこで囲みます。例えば、${request.path.name} ${request.path.id} です。

API レスポンスの変換

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

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

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

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

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

レスポンスパラメータのマッピング値
タイプ	構文	コメント
ヘッダー値	$response.header.name または ${response.header.name}	ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「予約済みヘッダー」を参照してください。
レスポンス本文	$response.body.name または ${response.body.name}	JSON パス式。再帰下降 ($response.body..name) およびフィルター式 (?(expression)) はサポートされていません。 注記 JSON パスを指定すると、API Gateway はレスポンス本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、$response.body を指定します。
コンテキスト変数	$context.variableName または ${context.variableName}	サポートされているコンテキスト変数の値。
ステージ変数	$stageVariables.variableName または ${stageVariables.variableName}	ステージ変数の値。
静的な値	文字列	定数値。

注記

選択式で複数の変数を使用するには、変数を角かっこで囲みます。例えば、${request.path.name} ${request.path.id} です。

予約済みヘッダー

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

• access-control-*

• apigw-*

• Authorization

• Connection

• Content-Encoding

• Content-Length

• Content-Location

• Forwarded

• Keep-Alive

• Origin

• Proxy-Authenticate

• Proxy-Authorization

• TE

• Trailers

• 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-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'