# API Gateway で HTTP API の API リクエストとレスポンスを変換する
<a name="http-api-parameter-mapping"></a>

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



## API リクエストの変換
<a name="http-api-mapping-request-parameters"></a>

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

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

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


| タイプ | 構文 | 
| --- | --- | 
| ヘッダー | append\|overwrite\|remove:header.{{headername}} | 
| クエリ文字列 | append\|overwrite\|remove:querystring.{{querystring-name}} | 
| パス | overwrite:path | 

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


| タイプ | 構文 | コメント | 
| --- | --- | --- | 
| ヘッダー値 | $request.header.{{name}} または ${request.header.{{name}}} | ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「[予約済みヘッダー](#http-api-mapping-reserved-headers)」を参照してください。 | 
| クエリ文字列値 | $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}}} | [コンテキスト変数](http-api-logging-variables.md)の値 。特殊文字の `.` と `_` のみがサポートされています。 | 
| ステージ変数 | $stageVariables.{{variableName}} または ${stageVariables.{{variableName}}} | [ステージ変数](http-api-stages.stage-variables.md)の値。 | 
| 静的な値 | {{string}} | 定数値。 | 

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

## API レスポンスの変換
<a name="http-api-mapping-response-parameters"></a>

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

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

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


| タイプ | 構文 | 
| --- | --- | 
| ヘッダー | append\|overwrite\|remove:header.{{headername}} | 
| ステータスコード | overwrite:statuscode | 

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


| タイプ | 構文 | コメント | 
| --- | --- | --- | 
| ヘッダー値 | $response.header.{{name}} または ${response.header.{{name}}} | ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。一部のヘッダーは予約されています。詳細については、「[予約済みヘッダー](#http-api-mapping-reserved-headers)」を参照してください。 | 
| レスポンス本文 | $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}}} | サポートされている[コンテキスト変数](http-api-logging-variables.md)の値。 | 
| ステージ変数 | $stageVariables.{{variableName}} または ${stageVariables.{{variableName}}} | [ステージ変数](http-api-stages.stage-variables.md)の値。 | 
| 静的な値 | {{string}} | 定数値。 | 

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

## 予約済みヘッダー
<a name="http-api-mapping-reserved-headers"></a>

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

## 例
<a name="http-api-parameter-mapping-examples"></a>

以下の AWS CLI 例は、パラメータマッピングを設定します。CloudFormation テンプレートの例については、[GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates) を参照してください。

### API リクエストへのヘッダーの追加
<a name="http-api-parameter-mapping-examples-request-header"></a>

次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、バックエンド統合に到達する前に 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" }'
```

### リクエストヘッダーの名前を変更する
<a name="http-api-parameter-mapping-examples-response"></a>

次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、リクエストヘッダーの名前を `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": "''"}'
```

### 統合からのレスポンスの変更
<a name="http-api-parameter-mapping-examples-response"></a>

次の [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、統合のレスポンスパラメータを設定します。インテグレーションが 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"}  }'
```

### 構成されたパラメータマッピングの削除
<a name="http-api-parameter-mapping-examples-remove"></a>

次の [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) コマンドは、`append:header.header1` に対して以前に設定されたリクエストパラメータを削除します。また、200 ステータスコードに対して以前に構成されたレスポンスパラメータも削除されます。

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