# 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)」を参照してください。