# API Gateway での REST API のデータ変換
**注記**
このセクションでは、非プロキシ統合で使用する関数について説明します。ただし、可能な場合は、REST API ではプロキシ統合を使用することをお勧めします。プロキシ統合にも合理化された統合設定があり、既存の設定を破棄することなくバックエンドで拡張できます。詳細については、「[API Gateway API 統合タイプの選択](api-gateway-api-integration-types.md)」を参照してください。
非プロキシ統合を使用する場合、API Gateway の 2 つの関数を使用して、メソッドリクエストと統合レスポンスを変換できます。統合リクエストのペイロードとは異なるペイロード形式を使用している場合は、メソッドリクエストを変換できます。メソッドレスポンスで返す必要がある形式とは異なるペイロード形式が返された場合、統合レスポンスを変換できます。リクエストのライフサイクルに関する詳細は、「[REST API のリソース例](rest-api-develop.md#rest-api-develop-example)」を参照してください。
次の例は、ヘッダー `"x-version:beta"` の場合、`x-version` ヘッダーパラメータが `app-version` ヘッダーパラメータに変換されるデータ変換を説明しています。`x-version` から `app-version` へのデータ変換は、統合リクエストで行われます。これにより、統合エンドポイントは変換されたヘッダーパラメータ値を受け取ります。統合エンドポイントがステータスコードを返すと、メソッドレスポンスの前にステータスコードが `200` から `204` に変換されます。
![\[API Gateway データ変換の図\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/develop-non-proxy.png)
データ変換を作成するには、以下の関数を使用できます。
**パラメータのマッピング**
パラメータマッピングで変更できるのは、統合リクエストの URL パスパラメータ、URL クエリ文字列パラメータ、または HTTP ヘッダー値です。統合リクエストペイロードは変更できません。HTTP レスポンスヘッダー値も変更できます。パラメータマッピングを使用して、Cross-Origin Resource Sharing(CORS) の静的ヘッダー値を作成します。
パラメータマッピングは、プロキシ統合と非プロキシ統合の統合リクエストでは使用できますが、統合レスポンスでは、非プロキシ統合を使用する必要があります。パラメータマッピングでは、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) でのスクリプトは必要ありません。詳細については、「[API Gateway の REST API パラメータマッピング](rest-api-parameter-mapping.md)」を参照してください。
**テンプレート変換のマッピング**
マッピングテンプレート変換では、マッピングテンプレートを使用して、URL パス パラメータ、URL クエリ文字列パラメータ、HTTP ヘッダー、統合リクエストまたは統合レスポンスの本文をマッピングします。*マッピングテンプレート*は、[JSONPath 式](https://goessner.net/articles/JsonPath/)を使用して [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で表現され、`Content-type` ヘッダーに基づいてペイロードに適用されるスクリプトです。
マッピングテンプレートでは、以下を実行できます。
+ Amazon DynamoDB や Lambda 関数などの AWS のサービス、または HTTP エンドポイントとの統合を使用して送信するデータを選択します。詳細については、「[チュートリアル: AWS サービスへの統合のための統合リクエストとレスポンスを変更する](set-up-data-transformations-in-api-gateway.md)」を参照してください。
+ API の統合リクエストと統合レスポンスパラメータを条件付きで上書きし、新しいヘッダー値を作成して、ステータスコードを上書きします。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。
統合リクエスト本文に一致するマッピングテンプレートがない `Content-type` ヘッダーがある場合の API の動作を指定することもできます。これは、統合パススルーの動作と呼ばれます。詳細については、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
## パラメータマッピングとマッピングテンプレート変換のどちらかを選択する
可能であれば、データの変換にはパラメータマッピングの使用をお勧めします。API で本文を変更する必要がある場合、または受信統合リクエストまたは統合レスポンスに基づいて条件付き上書きと変更を実行する必要がある場合に、プロキシ統合を使用できないときは、マッピングテンプレート変換を使用します。
# API Gateway の REST API パラメータマッピング
**注記**
HTTP API を使用している場合は、「[API Gateway で HTTP API の API リクエストとレスポンスを変換する](http-api-parameter-mapping.md)」を参照してください。
パラメータマッピングでは、リクエストまたはレスポンスパラメータをマッピングします。パラメータのマッピングには、パラメータマッピング式または静的な値を使用できます。マッピング式のリストについては、「[API Gateway での REST API パラメータマッピングのソースのリファレンス](rest-api-parameter-mapping-sources.md)」を参照してください。パラメータマッピングは、プロキシ統合と非プロキシ統合の統合リクエストでは使用できますが、統合レスポンスでは、非プロキシ統合を使用する必要があります。
例えば、メソッドリクエストヘッダーパラメータ `puppies` を統合リクエストヘッダーパラメータ `DogsAge0` にマッピングできます。その後、クライアントが API にヘッダー `puppies:true` を送信すると、統合リクエストはリクエストヘッダー `DogsAge0:true` を統合エンドポイントに送信します。次の図は、この例のリクエストライフサイクルを説明しています。
![\[リクエストの API Gateway パラメータマッピングの例の図\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
API Gateway を使用してこの例を作成するには、「[例 1: メソッドリクエストパラメータを統合リクエストパラメータにマッピングする](request-response-data-mappings.md#request-response-data-mappings-example-1)」を参照してください。
別の例としては、統合レスポンスヘッダーパラメータ `kittens` をメソッドレスポンスヘッダーパラメータ `CatsAge0` にマッピングすることもできます。その後、統合エンドポイントが `kittens:false` を返すと、クライアントはヘッダー `CatsAge0:false` を受け取ります。次の図は、この例のリクエストライフサイクルを説明しています。
![\[レスポンスの API Gateway パラメータマッピングの例の図\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [API Gateway での REST API パラメータマッピングの例](request-response-data-mappings.md)
+ [API Gateway での REST API パラメータマッピングのソースのリファレンス](rest-api-parameter-mapping-sources.md)
# API Gateway での REST API パラメータマッピングの例
次の例は、API Gateway コンソール、OpenAPI、CloudFormation テンプレートを使用して、パラメータマッピング式を作成する方法を説明しています。パラメータマッピングを使用して必要な CORS ヘッダーを作成する方法の例については、「[API Gateway での REST API の CORS](how-to-cors.md)」を参照してください。
## 例 1: メソッドリクエストパラメータを統合リクエストパラメータにマッピングする
次の例では、メソッドリクエストヘッダーパラメータ `puppies` を統合リクエストヘッダーパラメータ `DogsAge0` にマッピングします。
------
#### [ AWS マネジメントコンソール ]
**メソッドリクエストパラメータをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メソッドを選択します。
メソッドには非プロキシ統合が必要です。
1. **[メソッドリクエストの設定]** で、**[編集]** をクリックします。
1. **[HTTP リクエストヘッダー]** を選択します。
1. [**ヘッダーの追加**] を選択します。
1. **[Name]** (名前) には **puppies** を入力します。
1. **[保存]** を選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエストの設定]** で、**[編集]** を選択します。
AWS マネジメントコンソール は自動的に `method.request.header.puppies ` から `puppies` にパラメータマッピングを追加します。ただし、**[名前]** を統合エンドポイントで想定されるリクエストヘッダーパラメータと一致するように変更する必要があります。
1. **[Name]** (名前) には **DogsAge0** を入力します。
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
次の手順では、パラメータマッピングが正常に完了したかを確認する方法を説明します。
**(オプション) パラメータマッピングをテストする**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. [ヘッダー] には、**puppies:true** と入力します。
1. **[テスト]** を選択します。
1. **[ログ]** では結果が以下のようになります。
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
リクエストヘッダーパラメータが、`puppies` から `DogsAge0` に変更されました。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## 例 2: 複数のメソッドリクエストパラメータを別々の統合リクエストパラメータにマッピングする
次の例では、複数値メソッドリクエストクエリ文字列パラメータ `methodRequestQueryParam` を統合リクエストクエリ文字列パラメータ `integrationQueryParam` にマッピングして、メソッドリクエストヘッダーパラメータ `methodRequestHeaderParam` を統合リクエストパスパラメータ `integrationPathParam` にマッピングします。
------
#### [ AWS マネジメントコンソール ]
**複数のメソッドリクエストパラメータをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メソッドを選択します。
メソッドには非プロキシ統合が必要です。
1. **[メソッドリクエストの設定]** で、**[編集]** をクリックします。
1. **[URL クエリ文字列パラメータ]** を選択します。
1. [**クエリ文字列の追加**] を選択します。
1. **[Name]** (名前) には **methodRequestQueryParam** を入力します。
1. **[HTTP リクエストヘッダー]** を選択します。
1. [**ヘッダーの追加**] を選択します。
1. **[Name]** (名前) には **methodRequestHeaderParam** を入力します。
1. **[保存]** を選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[URL パスパラメータ]** を選択します。
1. **[パスパラメータを追加]** を選択します。
1. **[Name]** (名前) には **integrationPathParam** を入力します。
1. **[マッピング元]** として「**method.request.header.methodRequestHeaderParam**」と入力します。
これにより、メソッドリクエストで指定したメソッドリクエストヘッダーが新しい統合リクエストパスパラメータにマッピングされます。
1. **[URL クエリ文字列パラメータ]** を選択します。
1. [**クエリ文字列の追加**] を選択します。
1. **[Name]** (名前) には **integrationQueryParam** を入力します。
1. **[マッピング元]** として「**method.request.multivaluequerystring.methodRequestQueryParam**」と入力します。
これにより、複数値クエリ文字列パラメータが新しい単一値統合リクエストクエリ文字列パラメータにマッピングされます。
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
次の OpenAPI 定義は、HTTP 統合のために以下のパラメータマッピングを作成します。
+ `methodRequestHeaderParam` という名前のメソッドリクエストのヘッダーから、`integrationPathParam` という名前の統合リクエストパスパラメータへのマッピング
+ `methodRequestQueryParam` という名前の複数値のメソッドリクエストから、`integrationQueryParam` という名前の統合リクエストのクエリ文字列へのマッピング
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、HTTP 統合のために以下のパラメータマッピングを作成します。
+ `methodRequestHeaderParam` という名前のメソッドリクエストのヘッダーから、`integrationPathParam` という名前の統合リクエストパスパラメータへのマッピング
+ `methodRequestQueryParam` という名前の複数値のメソッドリクエストから、`integrationQueryParam` という名前の統合リクエストのクエリ文字列へのマッピング
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 例 3: JSON リクエスト本文のフィールドを統合リクエストパラメータにマッピングする
統合リクエストのパラメータは、[JSONPath 式](http://goessner.net/articles/JsonPath/index.html#e2) を使用して JSON リクエスト本文のフィールドからマッピングすることもできます。次の例では、メソッドリクエスト本文を `body-header` という名前の統合リクエストヘッダーにマッピングし、JSON 式で表されるリクエスト本文の一部を `pet-price` という名前の統合リクエストヘッダーにマッピングします。
この例をテストするには、次のような料金カテゴリを含む入力を指定します。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS マネジメントコンソール ]
**複数のメソッドリクエストパラメータをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. `POST` メソッド、`PUT` メソッド、`PATCH` メソッド、または `ANY` メソッドのいずれかを選択します。
メソッドには非プロキシ統合が必要です。
1. **[統合リクエストの設定]**で、**[編集]** を選択します。
1. **[URLリクエストヘッダーのパラメータ]** をクリックします。
1. **[リクエストヘッダーのパラメータを追加]** をクリックします。
1. **[Name]** (名前) には **body-header** を入力します。
1. **[マッピング元]** として「**method.request.body**」と入力します。
これにより、メソッドリクエスト本文が新しい統合リクエストヘッダーにマッピングされます。
1. **[リクエストヘッダーのパラメータを追加]** をクリックします。
1. **[Name]** (名前) には **pet-price** を入力します。
1. **[マッピング元]** として「** method.request.body[0].price**」と入力します。
これにより、メソッドリクエスト本文の一部が新しい統合リクエストヘッダーにマッピングされます。
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、JSON リクエスト本文の複数のフィールドから統合リクエストパラメータをマッピングします。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 例 4: 統合レスポンスをメソッドレスポンスにマッピングする
統合レスポンスをメソッドレスポンスにマップすることもできます。次の例では、統合レスポンス本文を `location` という名前のメソッドレスポンスヘッダーにマッピングし、統合レスポンスヘッダー `x-app-id` をメソッドレスポンスヘッダー `id` にマッピングして、複数値の統合レスポンスヘッダー `item` をメソッドレスポンスヘッダー `items` にマッピングします。
------
#### [ AWS マネジメントコンソール ]
**統合レスポンスをマッピングするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. REST API を選択します。
1. メソッドを選択します。
メソッドには非プロキシ統合が必要です。
1. **[メソッドレスポンス]** タブを選択して、**[レスポンス 200]** で **[編集]** を選択します。
1. **[ヘッダー名]** では、**[ヘッダーを追加]** を選択します。
1. **id**、**item**、**location** という名前の 3 つのヘッダーを作成します。
1. **[保存]** を選択します。
1. **[統合レスポンス]** タブをクリックして、**[デフォルト - レスポンス]** で、**[編集]** をクリックします。
1. **[ヘッダーのマッピング]** で、以下を入力します。
1. **[ID]** には **integration.response.header.x-app-id** と入力する
1. **[項目]** には **integration.response.multivalueheader.item** と入力する
1. **[場所]** には **integration.response.body.redirect.url** と入力する
1. **[保存]** を選択します。
1. 変更を有効にするには、API を再デプロイします。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、統合レスポンスをメソッドレスポンスにマッピングします。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# API Gateway での REST API パラメータマッピングのソースのリファレンス
パラメータマッピングを作成する際は、変更するメソッドリクエストまたは統合レスポンスパラメータを指定して、これらのパラメータを変更する方法を指定します。
次の表は、マッピングできるメソッドリクエストパラメータと、マッピングを作成する式をまとめています。これらの式での *name* はメソッドリクエストパラメータ名です。例えば、リクエストヘッダーパラメータ `puppies` をマッピングするには、`method.request.header.puppies` という式を使用します。式は、正規表現 `'^[a-zA-Z0-9._$-]+$]'` と一致する必要があります。プロキシ統合と非プロキシ統合の統合リクエストでは、パラメータマッピングを使用できます。
| **マッピングされたデータソース** | **マッピング式** |
| --- | --- |
| メソッドリクエストのパス | method.request.path.name |
| メソッドリクエストのクエリ文字列 | method.request.querystring.name |
| 複数値メソッドリクエストのクエリ文字列 | method.request.multivaluequerystring.name |
| メソッドリクエストのヘッダー | method.request.header.name |
| 複数値メソッドリクエストのヘッダー | method.request.multivalueheader.name |
| メソッドリクエストボディ | method.request.body |
| メソッドリクエストボディ (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* はリクエスト本文の JSON フィールドの JSONPath 式です。詳細については、「[JSONPath 式](http://goessner.net/articles/JsonPath/index.html#e2)」を参照してください。 |
| ステージ変数 | stageVariables.name |
| コンテキスト変数 | `context.name` 名前は、[サポートされるコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)のいずれかである必要があります。 |
| 静的な値 | `'static_value'`. *STATIC\$1VALUE* はリテラル文字列で、単一引用符のペアで囲まれている必要があります。例えば、`'https://www.example.com'`。 |
次の表は、マッピングできる統合レスポンスパラメータと、マッピングを作成する式をまとめています。これらの式での *name* はメ統合レスポンスパラメータ名です。メソッドレスポンスヘッダーは、任意の統合レスポンスヘッダーまたは統合レスポンス本文、\$1context 変数、または静的な値からマップできます。統合レスポンスでパラメータマッピングを使用するには、非プロキシ統合を使用する必要があります。
| マッピングされたデータソース | マッピング式 |
| --- | --- |
| 統合レスポンスのヘッダー | integration.response.header.name |
| 統合レスポンスのヘッダー | integration.response.multivalueheader.name |
| 統合レスポンスの本文 | integration.response.body |
| 統合レスポンスの本文 (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* はレスポンス本文の JSON フィールドの JSONPath 式です。詳細については、「[JSONPath 式](http://goessner.net/articles/JsonPath/index.html#e2)」を参照してください。 |
| ステージ変数 | stageVariables.name |
| コンテキスト変数 | `context.name` 名前は、[サポートされるコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)のいずれかである必要があります。 |
| 静的な値 | ` 'static_value'` *STATIC\$1VALUE* はリテラル文字列で、単一引用符のペアで囲まれている必要があります。例えば、`'https://www.example.com'`。 |
# API Gateway での REST API のテンプレート変換のマッピング
マッピングテンプレート変換では、統合リクエストまたは統合レスポンスの変更にマッピングテンプレートを使用します。*マッピングテンプレート*は、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で表現されるスクリプトであり、`Content-type` ヘッダーに基づいて [JSONPath](https://goessner.net/articles/JsonPath/) を使用してペイロードに適用されます。マッピングテンプレート変換を使用する場合は、マッピングテンプレートを使います。このセクションでは、マッピングテンプレートに関連する概念的な情報を説明します。
次の図は、PetStore 統合エンドポイントと統合されている `POST /pets` リソースのリクエストライフサイクルを説明しています。この API では、ユーザーはペットに関するデータを送信し、統合エンドポイントはペットの譲渡料金を返します。このリクエストライフサイクルでは、マッピングテンプレート変換が、リクエスト本文を統合エンドポイントにフィルタリングして、統合エンドポイントからレスポンス本文をフィルタリングします。
![\[リクエストライフサイクルの例\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/mapping-template-transforms.png)
以下のセクションでは、リクエストレスポンスのライフサイクルについて説明します。
## メソッドリクエストと統合リクエスト
前の例で、これがメソッドリクエストに送信されたリクエスト本文である場合:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
このリクエスト本文は、統合エンドポイントで使用される適切な形式ではないため、API Gateway はマッピングテンプレート変換を実行します。API Gateway は、Content-Type `application/json` 用に定義されたマッピングテンプレートがあるため、マッピングテンプレート変換のみを実行します。Content-Type のマッピングテンプレートを定義しない場合、デフォルトでは、API Gateway は統合リクエストを介して統合エンドポイントに本文を渡します。この動作を変更するには、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
次のマッピングテンプレートは、統合エンドポイントに送信される前に、統合リクエストのメソッドリクエストデータを変換します。
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. `$inputRoot` 変数は、前のセクションにおける元の JSON データのルートオブジェクトです。ディレクティブは `#` 記号で始まります。
1. `dog` は、ユーザーの `id` と文字列値を連結したものです。
1. `Age` はメソッドリクエスト本文からのものです。
次に、以下の出力が統合エンドポイントに転送されます。
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## 統合レスポンスとメソッドレスポンス
統合エンドポイントへのリクエストが正常に完了すると、エンドポイントは API Gateway の統合レスポンスにレスポンスを送信します。以下は、統合エンドポイントからの出力データの例です。
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
メソッドレスポンスは、統合レスポンスが返すペイロードとは異なるペイロードを想定しています。API Gateway はマッピングテンプレート変換を実行します。API Gateway は、Content-Type `application/json` 用に定義されたマッピングテンプレートがあるため、マッピングテンプレート変換のみを実行します。Content-Type のマッピングテンプレートを定義しない場合、デフォルトでは、API Gateway は統合レスポンスを介してメソッドレスポンスに本文を渡します。この動作を変更するには、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
以下の出力は、メソッドレスポンスに送信されます。
```
{"adoptionFee": 19.95}
```
これで、マッピングテンプレート変換の例は完了です。可能であれば、データの変換には、マッピングテンプレート変換を使用する代わりに、プロキシ統合を使用することをお勧めします。詳細については、「[API Gateway API 統合タイプの選択](api-gateway-api-integration-types.md)」を参照してください。
# API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作
メソッドリクエストにペイロードがあり、`Content-Type` ヘッダーにマッピングテンプレートが定義されていない場合は、クライアントが提供するリクエストペイロードを変換せずに統合リクエストを介してバックエンドに渡すことができます。このプロセスは統合パススルーと呼ばれます。
受信リクエストの実際のパススルー動作は、この設定によって決まります。3 つのオプションがあります。
**リクエストした Content-Type ヘッダーと一致するテンプレートがない場合**
メソッドリクエストのコンテンツタイプが、マッピングテンプレートと関連付けられたコンテンツタイプに一致しない場合に、統合リクエストをパススルーしてメソッドリクエスト本文を変換せずにバックエンドに渡す場合は、このオプションを選択します。
API Gateway API を呼び出すときは、[[統合]](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) の `passthroughBehavior` プロパティの値として `WHEN_NO_MATCH` を設定して、このオプションを選択します。
**テンプレートが定義されていない場合 (推奨)**
統合リクエストでマッピングテンプレートが定義されていないときに、統合リクエストをパススルーしてメソッドリクエスト本文を変換せずにバックエンドに渡す場合は、このオプションを選択します。このオプションを選択した際にテンプレートが定義されている場合、定義されたマッピングテンプレートのいずれにも一致しないペイロードとコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
API Gateway API を呼び出すときは、[[統合]](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) の `passthroughBehavior` プロパティの値として `WHEN_NO_TEMPLATES` を設定して、このオプションを選択します。
**なし**
統合リクエストでマッピングテンプレートが定義されていないときに、統合リクエストをパススルーしてメソッドリクエストボディを変換せずにバックエンドに渡さない場合は、このオプションを選択します。このオプションを選択したときにテンプレートが定義されている場合、マッピングされていないコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
API Gateway API を呼び出すときは、[[統合]](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) の `passthroughBehavior` プロパティの値として `NEVER` を設定して、このオプションを選択します。
次の例では、可能なパススルー動作について説明します。
例 1: `application/json` コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。
| Content-type | パススルーのオプション | 行動 |
| --- | --- | --- |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1MATCH | リクエストペイロードはテンプレートを使用して変換されます。 |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1TEMPLATES | リクエストペイロードはテンプレートを使用して変換されます。 |
| なし API Gateway のデフォルトは `application/json` | NEVER | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/json | WHEN\$1NO\$1MATCH | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/json | WHEN\$1NO\$1TEMPLATES | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/json | NEVER | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/xml | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/xml | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
例 2: `application/xml` コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。
| Content-type | パススルーのオプション | 行動 |
| --- | --- | --- |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1TEMPLATES | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| なし API Gateway のデフォルトは `application/json` | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/json | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/json | WHEN\$1NO\$1TEMPLATES | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/json | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/xml | WHEN\$1NO\$1MATCH | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | リクエストペイロードはテンプレートを使用して変換されます。 |
| application/xml | NEVER | リクエストペイロードはテンプレートを使用して変換されます。 |
例 3: 統合リクエストで定義されているマッピングテンプレートがない
| Content-type | パススルーのオプション | 行動 |
| --- | --- | --- |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| なし API Gateway のデフォルトは `application/json` | WHEN\$1NO\$1TEMPLATES | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| なし API Gateway のデフォルトは `application/json` | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/json | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/json | WHEN\$1NO\$1TEMPLATES | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/json | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
| application/xml | WHEN\$1NO\$1MATCH | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | リクエストペイロードは変換されず、そのままバックエンドに送信されます。 |
| application/xml | NEVER | リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 |
# 追加の API Gateway での REST API マッピングテンプレート例
次の例は、マッピングテンプレートを使用して統合リクエストと統合レスポンスデータを変換する API Gateway のフォトアルバム API を説明しています。この例では、データモデルを使用して、メソッドリクエストと統合レスポンスのペイロードも定義しています。データモデルの詳細については、「[REST API のデータモデル](models-mappings-models.md)」を参照してください。
## メソッドリクエストと統合リクエスト
以下は、メソッドリクエスト本文を定義するモデルです。この入力モデルでは、発信者が 1 ページの写真をアップロードする必要があり、ページごとに最低 10 枚の写真が必要です。この入力モデルを使用して SDK を生成したり、API のリクエストの検証に使用したりできます。リクエストの検証の使用中に、メソッドリクエスト本文がモデルのデータ構造に準拠していない場合、API Gateway はリクエストを失敗にします。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
以下は、上記のデータモデルのデータ構造に準拠するメソッドリクエスト本文の例です。
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
この例では、クライアントが上記のメソッドリクエスト本文を送信すると、このマッピングテンプレートは統合エンドポイントに必要な形式と一致するようにペイロードを変換します。
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
次の例は、変換からの出力データです。
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
このデータは統合リクエストに送信されてから、統合エンドポイントに送信されます。
## 統合レスポンスとメソッドレスポンス
以下は、統合エンドポイントからの写真データの出力モデルの例です。このモデルはメソッドレスポンスモデルに使用できます。これは、API 用に厳密に型指定した SDK を生成するときに必要です。これにより、出力が Java や Objective-C の適切なクラスにキャストされます。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
統合エンドポイントは、このモデルのデータ構造に準拠するレスポンスで応答しない場合があります。例えば、統合レスポンスは次のようになります。
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
次のマッピングテンプレートの例では、統合レスポンスデータをメソッドレスポンスで想定される形式に変換します。
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
次の例は、変換からの出力データです。
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
このデータはメソッドレスポンスに送信されてから、クライアントに送信されます。
# API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする
マッピングテンプレート変換を使用して、任意のタイプのリクエストパラメータ、レスポンスヘッダー、またはレスポンスステータスコードを上書きできます。マッピングテンプレートを使用して、以下を実行できます。
+ 多対 1 のパラメータマッピングを実行する
+ 標準 API Gateway マッピングが適用された適用された後にパラメータをオーバーライドする
+ 本文の内容やその他のパラメータ値に基づいて条件付きでパラメータをマッピングする
+ プログラムで新しいパラメータを作成する
+ 統合エンドポイントから返されたステータスコードをオーバーライドする
オーバーライドは最終的なものです。オーバーライドは各パラメータに一度だけ適用できます。同じパラメータを複数回オーバーライドしようとすると、API Gateway から `5XX` レスポンスが返されます。テンプレート全体で同じパラメータを複数回オーバーライドする必要がある場合は、変数を作成してテンプレートの終了時にオーバーライドを適用することをお勧めします。テンプレートはテンプレート全体が解析された後にのみ適用されます。
## 例 1: 統合本文に基づいてステータスコードを上書きする
次の例では、[サンプル API](api-gateway-create-api-from-example.md) を使用して、統合レスポンス本文に基づいてステータスコードを上書きします。
------
#### [ AWS マネジメントコンソール ]
**統合レスポンス本文に基づいてステータスコードを上書きするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. [**API の作成**] を選択します。
1. **[REST API]** では、**[構築]** を選択します。
1. **[API の詳細]** では、**[API の例]** を選択します。
1. **[API の作成]** を選択します。
API Gateway は、サンプルのペットストア API を作成します。ペットに関する情報を取得するには、`GET /pets/{petId}` の API メソッドリクエストを使用します。ここで、`{petId}` は、ペットの ID 番号に対応するパスパラメータです。
この例では、エラー状態が検出された場合、`GET` メソッドのレスポンスコードを `400` に上書きします。
1. **[リソース]** ツリーで、`/{petId}` の下の `GET` メソッドを選択します。
1. まず、API の現在の実装をテストします。
**[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[petId]** に「**-1**」と入力し、**[テスト]** を選択します。
**[レスポンス本文]** は、次のとおりの範囲外エラーを示します。
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
さらに、**[ログ]** の最後の行は `Method completed with status: 200` で終わります。
統合は正常に完了しましたが、エラーが発生しました。次に、統合本文に基づいてステータスコードを上書きします。
1. **[統合レスポンス]** タブの **[デフォルト - レスポンス]** で、**[編集]** を選択します。
1. **[マッピングテンプレート]** を選択します。
1. [**マッピングテンプレートの追加**] を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
このマッピングテンプレートは、統合レスポンスに `error` 文字列が含まれている場合、`$context.responseOverride.status` 変数を使用してステータスコードを `400` に上書きします。
1. **[保存]** を選択します。
1. **[テスト]** タブを選択します。
1. **[petId]** に「**-1**」と入力します。
1. 結果として、[**Response Body (レスポンス本文)**] は範囲外エラーを示します。
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
ただし、**[ログ]** の最後の行は、`Method completed with status: 400` で終わるようになりました。
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、`GET pets/{petId}` リソースを作成して、統合本文に基づいてステータスコードを上書きします。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## 例 2: リクエストヘッダーを上書きして新しいヘッダーを作成する
次の例では、[サンプル API](api-gateway-create-api-from-example.md) を使用してリクエストヘッダーを上書きして、新しいヘッダーを作成します。
------
#### [ AWS マネジメントコンソール ]
**新しいヘッダーを作成してメソッドのリクエストヘッダーを上書きするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. 前のチュートリアルで作成した API の例を選択します。API の名前は **[PetStore]** であるはずです。
1. **[リソース]** ツリーで、`/pet` の下の `GET` メソッドを選択します。
1. **[メソッドリクエスト]** タブの **[メソッドリクエストの設定]** で、**[編集]** を選択します。
1. **[HTTP リクエストヘッダー]** を選択した後、**[ヘッダーの追加]** を選択します。
1. **[Name]** (名前) には **header1** を入力します。
1. **[ヘッダーを追加]** を選択し、**header2** という名前の 2 つ目のヘッダーを作成します。
1. **[保存]** を選択します。
次に、マッピングテンプレートを使用して、これらのヘッダーを単一のヘッダー値に結合します。
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[リクエスト本文のパススルー]** で、**[テンプレートが定義されていない場合 (推奨)]** を選択します。
1. **[マッピングテンプレート]** を選択し、次の操作を行います。
1. [**マッピングテンプレートの追加**] を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
このマッピングテンプレートは、`header1` を文字列 `pets` で上書きし、`header1` と `header2` を組み合わせた `$header3Value` という名前の複数値ヘッダーを作成します。
1. **[保存]** を選択します。
1. **[テスト]** タブを選択します。
1. **[ヘッダー]** で、次のコードをコピーします。
```
header1:header1Val
header2:header2Val
```
1. [**Test (テスト)**] を選択します。
**[ログ]** には次のとおり、このテキストを含むエントリが表示されるはずです。
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
この例では、[body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) プロパティを使用して、OpenAPI 定義ファイルを API Gateway にインポートします。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
次の OpenAPI 定義は、リソース `GET pets` を作成し、リクエストヘッダーを上書きして新しいヘッダーを作成します。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
マッピングテンプレートの上書きを使用するには、マッピングテンプレートで以下の `$context` 変数のいずれかを使用します。`$context` 変数のリストについては、「[データ変換のコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)」を参照してください。
# チュートリアル: AWS サービスへの統合のための統合リクエストとレスポンスを変更する
次のチュートリアルでは、マッピングテンプレート変換を使用して、コンソールと AWS CLI で統合リクエストとレスポンスを変換するためのマッピングテンプレートを設定する方法を説明します。
**Topics**
+ [API Gateway コンソールを使用してデータ変換を設定する](#mapping-example-console)
+ [AWS CLI を使用してデータ変換を設定する](#mapping-example-cli)
+ [完成したデータ変換の CloudFormation テンプレート](#api-gateway-data-transformations-full-cfn-stack)
## API Gateway コンソールを使用してデータ変換を設定する
このチュートリアルでは、.zip ファイル ([data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip)) を使用して不完全な API と DynamoDB テーブルを作成します。この不完全な API には、`GET` メソッドと `POST` メソッドを持つ `/pets` リソースがあります。
+ `GET` メソッドは `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントからデータを取得します。出力データは、[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換されます。
+ `POST` メソッドを使用すると、ユーザーはマッピングテンプレートを使用して Amazon DynamoDB テーブルにペット情報を `POST` できます。
[CloudFormation のアプリケーション作成テンプレート](samples/data-transformation-tutorial-console.zip)をダウンロードして解凍します。このテンプレートを使用して、ペット情報と不完全な API を投稿するための DynamoDB テーブルを作成します。残りのステップは API Gateway コンソールで完了します。
**CloudFormation スタックを作成するには**
1. [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) で CloudFormation コンソール を開きます。
1. [**スタックの作成**] を選択し、[**With new resources (standard) 新しいリソースを使用 (標準)**] を選択します。
1. [**Specify template (テンプレートの指定)**] で、[**Upload a template file (テンプレートファイルのアップロード)**] を選択します。
1. ダウンロードしたテンプレートを選択します。
1. [**Next (次へ)**] を選択します。
1. [**Stack name**] (スタックの名前) で、**data-transformation-tutorial-console** と入力し、[**Next**] (次へ) を選択します。
1. [**Configure stack options**] (スタックオプションの設定) で、[**Next**] (次へ) を選択します。
1. [**Capabilities**] (機能) で、CloudFormation がアカウントに IAM リソースを作成できることを承認します。
1. **[次へ]** を選択し、**[送信]** を選択します。
CloudFormation は、テンプレートで指定されたリソースをプロビジョニングします。リソースのプロビジョニングには数分かかることがあります。CloudFormation スタックのステータスが **CREATE\$1COMPLETE** の場合は、次のステップに進む準備ができています。
**`GET` 統合レスポンスをテストするには**
1. **data-transformation-tutorial-console** の CloudFormation スタックの **[リソース]** タブで、API の物理 ID を選択します。
1. メインナビゲーションペインで **[リソース]**、**[GET]** メソッドの順に選択します。
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
テストの出力には、次の内容が表示されます。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
この出力を [API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換します。
**`GET` 統合レスポンスを変換するには**
1. **[統合レスポンス]** タブを選択します。
現在、マッピングテンプレートは定義されていないため、統合レスポンスは変換されません。
1. **[デフォルト - レスポンス]** で **[編集]** を選択します。
1. **[マッピングテンプレート]** を選択し、次の操作を行います。
1. [**マッピングテンプレートの追加**] を選択します。
1. **[コンテンツタイプ]** に、「**application/json**」と入力します。
1. **[テンプレート本文]** で次のように入力します。
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
**[保存]** を選択します。
**`GET` 統合レスポンスをテストするには**
+ **[テスト]** タブ、**[テスト]** の順に選択します。
テストの出力に、変換されたレスポンスが表示されます。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**`POST` メソッドからの入力データを変換するには**
1. **[POST]** メソッドを選択します。
1. **[統合リクエスト]** タブを選択し、**[統合リクエストの設定]** で、**[編集]** を選択します。
CloudFormation テンプレートでは、いくつかの統合リクエストフィールドが入力されています。
+ 統合タイプは AWS のサービスです。
+ AWS のサービスは DynamoDB です。
+ HTTP メソッドは `POST` です。
+ アクションは `PutItem` です。
+ API Gateway が DynamoDB テーブルに項目を入力できるようにする実行ロールは `data-transformation-tutorial-console-APIGatewayRole` です。CloudFormation は、API Gateway が DynamoDB とやり取りするための最小限のアクセス許可を持つように、このロールを作成済みです。
DynamoDB テーブルの名前は未指定です。次の手順に従って名前を指定します。
1. **[リクエスト本文のパススルー]** で、**[なし]** を選択します。
つまり、API はマッピングテンプレートを持たない Content-Type のデータを拒否します。
1. **[マッピングテンプレート]** を選択します。
1. **[コンテンツタイプ]** は `application/json` に設定されます。つまり、application/json 以外のコンテンツタイプは API によって拒否されます。統合パススルーの動作の詳細については、「[API Gateway で REST API のマッピングテンプレートを使用しないペイロードのメソッドリクエストの動作](integration-passthrough-behaviors.md)」を参照してください。
1. テキストエディタに次のコードを入力します。
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
このテンプレートでは、テーブルを `data-transformation-tutorial-console-ddb` として指定し、項目を `id`、`type`、`price` として設定します。項目は、`POST` メソッドの本体から取得されます。データモデルを使用してマッピングテンプレートを作成することもできます。詳細については、「[API Gateway での REST API のリクエスト検証](api-gateway-method-request-validation.md)」を参照してください。
1. **[保存]** ボタンを選択し、マッピングテンプレートを保存します。
**`POST` メソッドからメソッドと統合レスポンスを追加するには**
CloudFormation は、空白のメソッドと統合レスポンスを作成済みです。このレスポンスを編集して詳細情報を入力します。レスポンスの編集方法の詳細については、「[API Gateway での REST API パラメータマッピングの例](request-response-data-mappings.md)」を参照してください。
1. **[統合レスポンス]** タブの **[デフォルト - レスポンス]** で、**[編集]** を選択します。
1. **[マッピングテンプレート]**、**[マッピングテンプレートの追加]** の順に選択します。
1. **[コンテンツタイプ]** に「**application/json**」と入力します。
1. コードエディタで、次の出力マッピングテンプレートを入力し、出力メッセージを送信します。
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
コンテキスト変数の詳細については、「[データ変換のコンテキスト変数](api-gateway-mapping-template-reference.md#context-variable-reference)」を参照してください。
1. **[保存]** ボタンを選択し、マッピングテンプレートを保存します。
**`POST` メソッドをテストする**
**[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. リクエスト本文に、次の例を入力します。
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. **[テスト]** を選択します。
出力に成功メッセージが表示されるはずです。
DynamoDB コンソール ([https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)) を開いて、サンプル項目がテーブルにあることを確認できます。
**CloudFormation スタックを削除するには**
1. CloudFormation コンソール ([https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)) を開きます。
1. CloudFormation スタックを選択します。
1. [**Delete**] (削除) を選択し、選択を確定します。
## AWS CLI を使用してデータ変換を設定する
このチュートリアルでは、.zip ファイル ([data-transformation-tutorial-cli.zip](samples/data-transformation-tutorial-cli.zip)\$1 を使用して不完全な API と DynamoDB テーブルを作成します。この不完全な API には、`http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントと統合された `GET` メソッドを持つ `/pets` リソースがあります。`POST` メソッドを作成して DynamoDB テーブルに接続し、マッピングテンプレートを使用して DynamoDB テーブルにデータを入力します。
+ 出力データは、[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換します。
+ `POST` メソッドを作成し、ユーザーがマッピングテンプレートを使用して Amazon DynamoDB テーブルにペット情報を `POST` できるようにします。
**CloudFormation スタックを作成するには**
[CloudFormation のアプリケーション作成テンプレート](samples/data-transformation-tutorial-cli.zip)をダウンロードして解凍します。
次のチュートリアルを完了するには、[AWS Command Line Interface (AWS CLI) バージョン 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) が必要です。
コマンドが長い場合は、エスケープ文字 (`\`) を使用してコマンドを複数行に分割します。
**注記**
Windows では、一般的に使用する Bash CLI コマンドの一部 (`zip` など) が、オペレーティングシステムの組み込みターミナルでサポートされていません。Ubuntu および Bash の Windows 統合バージョンを取得するには、[Windows Subsystem for Linux をインストール](https://learn.microsoft.com/en-us/windows/wsl/install)します。このガイドの CLI コマンドの例では、Linux フォーマットを使用しています。Windows CLI を使用している場合、インライン JSON ドキュメントを含むコマンドを再フォーマットする必要があります。
1. 次のコマンドを使用して CloudFormation スタックを作成します。
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation は、テンプレートで指定されたリソースをプロビジョニングします。リソースのプロビジョニングには数分かかることがあります。次のコマンドを使用して CloudFormation スタックのステータスを確認します。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. CloudFormation スタックのステータスが `StackStatus: "CREATE_COMPLETE"` になったら、次のコマンドを使用して関連する出力値を取得し、以後のステップで使用します。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
出力値は以下のとおりです。
+ ApiRole。API Gateway が DynamoDB テーブルに項目を配置できるようにするロールの名前です。このチュートリアルの場合、ロール名は `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG` です。
+ DDBTableName。DynamoDB テーブルの名前です。このチュートリアルの場合、インスタンス名は `data-transformation-tutorial-cli-ddb` です。
+ ResourceId。`GET` メソッドと `POST` メソッドを公開するペットリソースの ID です。このチュートリアルの場合、リソース ID は `efg456` です。
+ ApiId。API の ID です。このチュートリアルの場合、API の ID は `abc123` です。
**データ変換の前に `GET` メソッドをテストするには**
+ 次のコマンドを使用して、`GET` メソッドをテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
テストの出力には、次の内容が表示されます。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
この出力を [API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換します。
**`GET` 統合レスポンスを変換するには**
+ 次のコマンドを使用して、`GET` メソッドの統合レスポンスを更新します。*rest-api-id* と *resource-id* を実際の値に置き換えます。
次のコマンドを使用して統合レスポンスを作成します。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**`GET` メソッドをテストするには**
+ 次のコマンドを使用して `GET` メソッドをテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
テストの出力に、変換されたレスポンスが表示されます。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**`POST` メソッドを作成するには**
1. 次のコマンドを使用して、`/pets` リソースで新しいメソッドを作成します。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
このメソッドを使用すると、CloudFormation スタックで作成した DynamoDB テーブルにペット情報を送信できます。
1. 次のコマンドを使用して、`POST` メソッドで AWS のサービス統合を作成します。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. 次のコマンドを使用して、`POST` メソッドの呼び出しが成功した場合のメソッドレスポンスを作成します。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 次のコマンドを使用して、`POST` メソッドの呼び出しが成功した場合の統合レスポンスを作成します。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**`POST` メソッドをテストするには**
+ 次のコマンドを使用して、`POST` メソッドをテストします。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
出力に、成功のメッセージが表示されます。
**CloudFormation スタックを削除するには**
+ 次のコマンドを使用して CloudFormation リソースを削除します。
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## 完成したデータ変換の CloudFormation テンプレート
次の例は、完成した CloudFormation テンプレートです。これにより、API と、`GET` メソッドと `POST` メソッドを持つ `/pets` リソースを作成します。
+ `GET` メソッドは、`http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP エンドポイントからデータを取得します。出力データは、[API Gateway での REST API のテンプレート変換のマッピング](models-mappings.md) のマッピングテンプレートに従って変換されます。
+ `POST` メソッドを使用すると、ユーザーはマッピングテンプレートを使用して DynamoDB テーブルにペット情報を `POST` できます。
### CloudFormation テンプレートの例
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# API Gateway のテンプレート変換のマッピングに変数を使用する例
以下の例は、マッピングテンプレートで `$context` 変数、`input` 変数、`util` 変数を使用する方法を説明しています。入力イベントを API Gateway に返すモック統合または Lambda 非プロキシ統合を使用できます。サポートされているデータ変換のすべての変数のリストについては、「[API Gateway のデータ変換の変数](api-gateway-mapping-template-reference.md)」を参照してください。
## 例 1: 統合エンドポイントに複数の `$context` 変数を渡す
次の例は、統合リクエストペイロード内で、受信 `$context` 変数をわずかに異なる名前のバックエンド変数にマッピングするマッピングテンプレートを示しています。
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
変数の 1 つは API キーです。この例では、メソッドが 1 つの API キーを要求することを前提としています。
## 例 2: すべてのリクエストパラメータを JSON ペイロードを介して統合エンドポイントに渡す
次の例では、`path` パラメータ、`querystring` パラメータ、`header` パラメータを含むすべてのリクエストパラメータを JSON ペイロードを介して統合エンドポイントに渡します。
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
リクエストに次の入力パラメータがある場合:
+ `myparam` という名前のパスパラメータ
+ クエリ文字列パラメータ `querystring1=value1,value2`
+ ヘッダー `"header1" : "value1"`
このマッピングテンプレートの出力は、次のようになります。
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## 例 3: メソッドリクエストのサブセクションを統合エンドポイントに渡す
次の例では、入力パラメータ `name` を使用して、パラメータ `name` のみを取得し、入力パラメータ `input.json('$')` を使用してメソッドリクエスト本文全体を取得します。
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
クエリ文字列パラメータ `name=Bella&type=dog` と次の本文を含むリクエストの場合:
```
{
"Price" : "249.99",
"Age": "6"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
このマッピングテンプレートは、クエリ文字列パラメータ `type=dog` を削除します。
JSON の入力に JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は 400 レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、`$util.escapeJavaScript($input.json('$'))` を適用します。
前の例に `$util.escapeJavaScript($input.json('$'))` を適用した結果は次のとおりです。
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
この場合、このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## 例 4: JSONPath 式を使用してメソッドリクエストのサブセクションを統合エンドポイントに渡す
次の例では、JSONPath 式を使用して、リクエスト本文から入力パラメータ `name` と `Age` のみを取得します。
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
クエリ文字列パラメータ `name=Bella&type=dog` と次の本文を含むリクエストの場合:
```
{
"Price" : "249.99",
"Age": "6"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body" : "6"
}
```
このマッピングテンプレートは、クエリ文字列パラメータ `type=dog` と `Price` フィールドを本文から削除します。
メソッドリクエストのペイロードに JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は `400` レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、`$util.escapeJavaScript()` を適用します。
前の例に `$util.escapeJavaScript($input.json('$.Age'))` を適用した結果は次のとおりです。
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
この場合、このマッピングテンプレートの出力は、次のようになります。
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## 例 5: JSONPath 式を使用してメソッドリクエストに関する情報を統合エンドポイントに渡す
次の例では、`$input.params()`、`$input.path()`、`$input.json()` を使用して、メソッドリクエストに関する情報を統合エンドポイントに送信します。このマッピングテンプレートは、`size()` メソッドを使用してリスト内の要素の数を提供します。
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
パスパラメータ `123` と次の本文を含むリクエストの場合:
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
メソッドリクエストのペイロードに JavaScript で解析できない文字がエスケープされずに含まれている場合、API Gateway は `400` レスポンスを返すことがあります。JSON の入力を正しく解析できるようにするには、`$util.escapeJavaScript()` を適用します。
前の例に `$util.escapeJavaScript($input.json('$.things'))` を適用した結果は次のとおりです。
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
このマッピングテンプレートの出力は、次のようになります。
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# API Gateway のデータ変換の変数
パラメータマッピングを作成する場合、データソースとしてコンテキスト変数を使用できます。マッピングテンプレート変換を作成する場合、[Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) で記述するスクリプトでコンテキスト変数、入力変数、util 変数を使用できます。これらの参照変数を使用するマッピングテンプレートの例については、「[API Gateway のテンプレート変換のマッピングに変数を使用する例](api-gateway-mapping-variable-examples.md)」を参照してください。
アクセスのログ記録の参照変数のリストについては、「[API Gateway のアクセスのログ記録のための変数](api-gateway-variables-for-access-logging.md)」を参照してください。
## データ変換のコンテキスト変数
データ変換には、次の大文字と小文字が区別される `$context` 変数を使用できます。
| パラメータ | 説明 |
| --- | --- |
| \$1context.accountId | API 所有者の AWS アカウント ID。 |
| \$1context.apiId | API Gateway が API に割り当てる識別子。 |
| \$1context.authorizer.claims.property | メソッドの呼び出し側が認証に成功した後に Amazon Cognito ユーザープールから返されるクレームのプロパティ。詳細については、「[Amazon Cognito ユーザープールをオーソライザーとして使用して REST API へのアクセスを制御する](apigateway-integrate-with-cognito.md)」を参照してください。 `$context.authorizer.claims` を呼び出すと NULL が返されます。 |
| \$1context.authorizer.principalId | クライアントにより送信され、API Gateway Lambda オーソライザー (以前のカスタムオーソライザー) から返されたトークンと関連付けられたプリンシパルユーザー ID。詳細については、「[API Gateway Lambda オーソライザーを使用する](apigateway-use-lambda-authorizer.md)」を参照してください。 |
| \$1context.authorizer.property | API Gateway Lambda オーソライザーの関数から返された `context` マップの指定されたキー/値ペアの文字列化された値。たとえば、オーソライザーが次の `context` マップを返すとします。 "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} `$context.authorizer.key` の呼び出しでは `"value"` 文字列が返され、`$context.authorizer.numKey` の呼び出しでは `"1"` 文字列が返され、`$context.authorizer.boolKey` の呼び出しでは `"true"` 文字列が返されます。 *プロパティ* でサポートされる特殊文字は、アンダースコア `(_)` 文字のみです。 詳細については、「[API Gateway Lambda オーソライザーを使用する](apigateway-use-lambda-authorizer.md)」を参照してください。 |
| \$1context.awsEndpointRequestId | AWS エンドポイントのリクエスト ID |
| \$1context.deploymentId | API デプロイの ID。 |
| \$1context.domainName | API の呼び出しに使用された完全ドメイン名。これは、受信 `Host` ヘッダーと同じである必要があります。 |
| \$1context.domainPrefix | `$context.domainName` の 1 つ目のラベル。 |
| \$1context.error.message | API Gateway のエラーメッセージを含む文字列。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、[GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文マッピングテンプレートの単純な変数の置換でのみ使用できます。詳細については、「[CloudWatch メトリクスを使用して WebSocket API の実行をモニタリングする](apigateway-websocket-api-logging.md)」および「[エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)」を参照してください。 |
| \$1context.error.messageString | \$1context.error.message を引用符で囲んだ値、つまり "\$1context.error.message"。 |
| \$1context.error.responseType | [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) の [type](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)。この変数は、Velocity Template Language エンジン、およびアクセスログ記録では処理されない、[GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 本文マッピングテンプレートの単純な変数の置換でのみ使用できます。詳細については、「[CloudWatch メトリクスを使用して WebSocket API の実行をモニタリングする](apigateway-websocket-api-logging.md)」および「[エラーレスポンスをカスタマイズするためのゲートウェイレスポンスのセットアップ](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)」を参照してください。 |
| \$1context.error.validationErrorString | 詳細な検証エラーメッセージを含む文字列。 |
| \$1context.extendedRequestId | API Gateway が生成して API リクエストに割り当てる拡張 ID。拡張リクエスト ID には、デバッグとトラブルシューティングに役立つ情報が含まれています。 |
| \$1context.httpMethod | 使用される HTTP メソッドです。有効な値には、`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` および `PUT` があります。 |
| \$1context.identity.accountId | リクエストに関連付けられた AWS アカウント ID です。 |
| \$1context.identity.apiKey | API キーを必要とする API メソッドの場合、この変数はメソッドリクエストに関連付けられている API キーです。API キーを必要としないメソッドの場合、この変数は null になります。詳細については、「[API Gateway での REST API の使用量プランと API キー](api-gateway-api-usage-plans.md)」を参照してください。 |
| \$1context.identity.apiKeyId | API キーを必要とする API リクエストに関連付けられた API キー ID。 |
| \$1context.identity.caller | リクエストに署名した発信者のプリンシパル ID。IAM 認可を使用するリソースでサポートされています。 |
| \$1context.identity.cognitoAuthenticationProvider | リクエスト元の発信者が使用するすべての Amazon Cognito 認証プロバイダーのカンマ区切りのリスト。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。 たとえば、Amazon Cognito ユーザープールのアイデンティティの場合、`cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 利用可能な Amazon Cognito 認証プロバイダーについては、「Amazon Cognito 開発者ガイド」の「[フェデレーティッド ID の使用](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)」を参照してください。** |
| \$1context.identity.cognitoAuthenticationType | リクエストを行う発信者の Amazon Cognito 認証タイプ。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。有効な値は、認証されたアイデンティティ`authenticated`および認証されていないアイデンティティ`unauthenticated`です。 |
| \$1context.identity.cognitoIdentityId | リクエストを行う発信者の Amazon Cognito ID。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。 |
| \$1context.identity.cognitoIdentityPoolId | リクエストを行う発信者の Amazon Cognito ID プール ID。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。 |
| \$1context.identity.principalOrgId | [AWS 組織 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)。 |
| \$1context.identity.sourceIp | API Gateway エンドポイントへのリクエストを行う即時 TCP 接続のソース IP アドレス。 |
| \$1context.identity.clientCert.clientCertPem | クライアントが相互 TLS 認証中に提示した PEM エンコードされたクライアント証明書。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.subjectDN | クライアントが提示する証明書のサブジェクトの識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.issuerDN | クライアントが提示する証明書の発行者の識別名。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.serialNumber | 証明書のシリアル番号。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.validity.notBefore | 証明書が無効になる前の日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.clientCert.validity.notAfter | 証明書が無効になった日付。相互 TLS が有効なカスタムドメイン名を使用してクライアントが API にアクセスすると、アクセスログに存在します。相互 TLS 認証が失敗した場合にのみ、アクセスログに存在します。 |
| \$1context.identity.vpcId | API Gateway エンドポイントへのリクエストを行う VPC の VPC ID。 |
| \$1context.identity.vpceId | API Gateway エンドポイントへのリクエストを行う VPC エンドポイントの VPC エンドポイント ID。プライベート API がある場合にのみ表示されます。 |
| \$1context.identity.user | リソースアクセスに対して許可されるユーザーのプリンシパル識別子。IAM 認可を使用するリソースでサポートされています。 |
| \$1context.identity.userAgent | API 発信者の [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) ヘッダー。 |
| \$1context.identity.userArn | 認証後に識別された有効ユーザーの Amazon リソースネーム (ARN) です。詳細については、「[https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)」を参照してください。 |
| \$1context.isCanaryRequest | リクエストが canary に送信された場合は `true` を返し、リクエストが canary に送信されなかった場合は `false` を返します。canary が有効になっている場合にのみ表示されます。 |
| \$1context.path | リクエストパス。たとえば、https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child の非プロキシリクエスト URL の場合、\$1context.path 値は /\$1stage\$1/root/child。 |
| \$1context.protocol | HTTP/1.1 などのリクエストプロトコル。 API Gateway API は HTTP/2 リクエストを受け入れることができますが、API Gateway は HTTP/1.1 を使用してバックエンド統合にリクエストを送信します。その結果、クライアントが HTTP/2 を使用するリクエストを送信した場合でも、リクエストプロトコルは HTTP/1.1 として記録されます。 |
| \$1context.requestId | リクエストの ID。クライアントは、このリクエスト ID を上書きできます。API Gateway が生成する一意のリクエスト ID に `$context.extendedRequestId` を使用します。 |
| \$1context.requestOverride.header.header\$1name | リクエストヘッダーオーバーライド。このパラメータが定義されている場合、[**Integration Request (統合リクエスト)**] ペインで定義されている [**HTTP Headers (HTTP ヘッダー)**] の代わりに使用されるヘッダーが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.requestOverride.path.path\$1name | リクエストパスオーバーライド。このパラメータが定義されている場合、[**Integration Request (統合リクエスト)**] ペインで定義されている [**URL Path Parameters (URL パスパラメータ)**] の代わりに使用されるリクエストパスが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.requestOverride.querystring.querystring\$1name | リクエストクエリ文字列オーバーライド。このパラメータが定義されている場合、[**Integration Request (統合リクエスト)**] ペインで定義されている [**URL Query String Parameters (URL クエリ文字列パラメータ)**] の代わりに使用されるリクエストクエリ文字列が含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.responseOverride.header.header\$1name | レスポンスヘッダーオーバーライド。このパラメータが定義されている場合、[Integration Response (統合レスポンス)] ペインの [Default mapping (デフォルトのマッピング)] として定義されている [Response header (レスポンスヘッダー)] の代わりに返されるヘッダーが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.responseOverride.status | レスポンスステータスコードオーバーライド。このパラメータが定義されている場合、[Integration Response (統合レスポンス)] ペインの [Default mapping (デフォルトのマッピング)] として定義されている [Method response status (メソッドレスポンスのステータス)] の代わりに返されるステータスコードが含まれます。詳細については、「[API Gateway で REST API の API リクエストパラメータおよびレスポンスパラメータとステータスコードを上書きする](apigateway-override-request-response-parameters.md)」を参照してください。 |
| \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 形式の要求時間 (dd/MMM/yyyy:HH:mm:ss \$1-hhmm)。 |
| \$1context.requestTimeEpoch | [エポック](https://en.wikipedia.org/wiki/Unix_time)形式のリクエスト時間 (ミリ秒単位)。 |
| \$1context.resourceId | API Gateway がリソースに割り当てる識別子です。 |
| \$1context.resourcePath | リソースへのパスです。たとえば、`https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` の非プロキシリクエスト URI の場合、`$context.resourcePath` 値は `/root/child`。詳細については、「[チュートリアル: HTTP 非プロキシ統合を使用して REST API を作成する](api-gateway-create-api-step-by-step.md)」を参照してください。 |
| \$1context.stage | API リクエストのデプロイステージ (`Beta`、`Prod` など)。 |
| \$1context.wafResponseCode | [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) から受け取ったレスポンス: `WAF_ALLOW` または `WAF_BLOCK`。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「[AWS WAF を使用して API Gateway の REST API を保護する](apigateway-control-access-aws-waf.md)」を参照してください。 |
| \$1context.webaclArn | リクエストを許可するかブロックするかを決定するために使用されるウェブ ACL の完全な ARN。ステージがウェブ ACL に関連付けられていない場合は、設定されません。詳細については、「[AWS WAF を使用して API Gateway の REST API を保護する](apigateway-control-access-aws-waf.md)」を参照してください。 |
## 入力変数
次の大文字と小文字が区別される `$input` 変数を使用して、メソッドリクエストペイロードとメソッドリクエストパラメータを参照できます。以下の機能を使用できます。
| 変数と関数 | 説明 |
| --- | --- |
| \$1input.body | 文字列として raw リクエストペイロードを返します。`$input.body` を使用して、浮動小数点数全体 (`10.00` など) を保持できます。 |
| \$1input.json(x) | この関数は、JSONPath の式を評価し、結果を JSON 文字列で返します。 たとえば `$input.json('$.pets')` は、`pets` 構造を表す JSON 文字列を返します。 JSONPath の詳細については、[JSONPath](https://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/json-path/JsonPath) を参照してください。 |
| \$1input.params() | すべてのリクエストパラメータのマップを返します。インジェクション攻撃の可能性を避けるため、`$util.escapeJavaScript` を使用して結果をサニタイズすることをお勧めします。リクエストのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。 |
| \$1input.params(x) | パラメータ名文字列 `x` が指定された場合に、パス、クエリ文字列、またはヘッダー値から (この順番で検索される) メソッドリクエストパラメータの値を返します。インジェクション攻撃の可能性を避けるため、`$util.escapeJavaScript` を使用してパラメータをサニタイズすることをお勧めします。パラメータのサニタイズを完全に制御するには、テンプレートなしでプロキシ統合を使用し、統合でリクエストのサニタイズを処理します。 |
| \$1input.path(x) | JSONPath 式文字列 (`x`) を受け取り、結果の JSON オブジェクト表現を返します。これにより、[Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) でペイロード要素にネイティブにアクセスして操作できます。 たとえば、式 `$input.path('$.pets')` が次のようにオブジェクトを返すとします。 [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()` は を返します。`"3"` JSONPath の詳細については、[JSONPath](https://goessner.net/articles/JsonPath/) または [JSONPath for Java](https://github.com/json-path/JsonPath) を参照してください。 |
## ステージ変数
メソッド統合では、次のステージ変数を ARN と URL のプレースホルダーとして使用できます。詳細については、「[API Gateway で REST API のステージ変数を使用する](stage-variables.md)」を参照してください。
| 構文 | 説明 |
| --- | --- |
| \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'], または \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* はステージ変数名を表します。 |
## Util 変数
マッピングテンプレートのユーティリティ関数を使用するには、次の大文字と小文字が区別される `$util` 変数を使用できます。別に指定されていない限り、デフォルトの文字は UTF-8 に設定されます。
| 関数 | 説明 |
| --- | --- |
| \$1util.escapeJavaScript() | JavaScript 文字列ルールを使用して文字列内の文字をエスケープします。 この関数は、通常の一重引用符 (`'`) をエスケープした一重引用符 (`\'`) に変換します。ただし、エスケープした一重引用符は JSON で有効ではありません。したがって、この関数からの出力を JSON のプロパティで使用する場合、エスケープした一重引用符 (`\'`) を通常の一重引用符 (`'`) に戻す必要があります。これを次の例で示します: "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | "stringified" JSON を受け取り、結果のオブジェクト表現を返します。この関数の結果を使用して、Apache Velocity Template Language (VTL) でペイロード要素にネイティブにアクセスしてこれらの要素を操作できるようになります。たとえば、次のペイロードがあるとします。 {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} さらに、次のマッピングテンプレートを使用するとします。 #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
この場合、次の出力が返されます。 {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | 文字列を「application/x-www-form-urlencoded」形式に変換します。 |
| \$1util.urlDecode() | 「application/x-www-form-urlencoded」文字列をデコードします。 |
| \$1util.base64Encode() | データを base64 エンコードされた文字列にエンコードします。 |
| \$1util.base64Decode() | base64 エンコードされた文字列からデータをデコードします。 |