# 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\$1overwrite\$1remove:header.headername | 
| クエリ文字列 | append\$1overwrite\$1remove:querystring.querystring-name | 
| パス | overwrite:path | 

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


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

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


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

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

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

次のヘッダーは予約されています。これらのヘッダーには、要求またはレスポンスマッピングを構成できません。
+ access-control-\$1
+ apigw-\$1
+ Authorization
+ Connection
+ Content-Encoding
+ Content-Length
+ Content-Location
+ Forwarded
+ Keep-Alive
+ Origin
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers 
+ Transfer-Encoding
+ Upgrade
+ x-amz-\$1
+ x-amzn-\$1
+ 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" : {}}'
```