API Gateway で HTTP API の API リクエストとレスポンスを変換する - Amazon API Gateway
API リクエストの変換API レスポンスの変換予約済みヘッダー例

API Gateway で HTTP API の 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} ステージ変数の値。
静的な値 string 定数値。
注記

選択式で複数の変数を使用するには、変数を角かっこで囲みます。例えば、${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 path 式。再帰下降 ($response.body..name) およびフィルター式 (?(expression)) はサポートされていません。
注記

JSON パスを指定すると、API Gateway はレスポンス本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、$response.body を指定します。
コンテキスト変数 $context.variableName または ${context.variableName} サポートされているコンテキスト変数の値。
ステージ変数 $stageVariables.variableName または ${stageVariables.variableName} ステージ変数の値。
静的な値 string 定数値。
注記

選択式で複数の変数を使用するには、変数を角かっこで囲みます。例えば、${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 リクエストへのヘッダーの追加

次の create-integration コマンドは、バックエンド統合に到達する前に 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" }'

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

次の create-integration コマンドは、リクエストヘッダーの名前を 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": "''"}'

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

次の create-integration コマンドは、統合のレスポンスパラメータを設定します。インテグレーションが 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"}  }'

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

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

aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'