针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码
您可以使用映射模板转换来覆盖任何类型的请求参数、响应标头或响应状态代码。可以使用映射模板来执行以下操作:
-
执行多对一参数映射
-
在应用标准 API Gateway 映射后覆盖参数
-
根据正文内容或其他参数值有条件地映射参数
-
以编程方式创建新参数
-
覆盖由集成端点返回的状态代码
覆盖是最终的。对于每个参数,覆盖只能应用一次。如果您多次尝试覆盖同一个参数,则 API Gateway 会返回 5XX
响应。如果您必须在整个模板中多次覆盖相同的参数,我们建议创建一个变量并在模板末尾应用覆盖。仅在解析整个模板后应用模板。
示例 1:基于集成正文覆盖状态代码
以下示例使用示例 API 基于集成响应正文覆盖状态代码。
- AWS Management Console
-
基于集成响应正文覆盖状态代码
通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway
。 -
选择创建 API。
-
对于 REST API,选择构建。
-
对于 API 详细信息,选择示例 API。
-
选择创建 API。
API Gateway 创建一个示例宠物商店 API。要检索有关宠物的信息,您使用 API 方法请求
GET /pets/{petId}
,其中{petId}
是与宠物的 ID 号相对应的路径参数。在此示例中,当检测到错误条件时,您将
GET
方法的响应代码覆盖为400
。 -
在资源树中,选择
/{petId}
下的GET
方法。 -
首先,测试 API 的当前实现。
选择测试选项卡。您可能需要选择右箭头按钮,以显示该选项卡。
-
对于 petId,输入
-1
,然后选择测试。响应正文指示超出范围错误:
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }
此外,日志下的最后一行的结尾为:
Method completed with status: 200
。集成已成功完成,但出现错误。现在,您将根据集成响应覆盖状态代码。
-
在集成响应选项卡上,对于默认 - 响应,选择编辑。
-
选择映射模板。
-
选择添加映射模板。
-
对于内容类型,输入
application/json
。 -
对于模板正文,输入以下内容:
#set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end
如果集成响应包含字符串
error
,则此映射模板使用$context.responseOverride.status
变量将状态代码覆盖为400
。 -
选择保存。
-
选择测试选项卡。
-
对于 petId,输入
-1
。 -
在结果中,响应正文表示超出范围错误:
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }
不过,日志下的最后一行现在的结尾为:
Method completed with status: 400
。
- AWS CloudFormation
-
在此示例中,您使用 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 来覆盖请求标头并创建新的标头。
- AWS Management Console
通过创建新标头覆盖方法的请求标头
通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway
。 -
选择您在先前教程中创建的示例 API。API 的名称应为 PetStore。
-
在资源树中,选择
/pet
下的GET
方法。 -
在方法请求选项卡上,对于方法请求设置,选择编辑。
-
选择 HTTP 请求标头,然后选择添加标头。
-
对于名称,请输入
header1
。 -
选择添加标头,然后创建第二个标头,名为
header2
。 -
选择保存。
现在,您可以使用映射模板将这些标头合并为一个标头值。
-
在集成请求选项卡上,对于集成请求设置,选择编辑。
-
对于请求正文传递,选择当未定义模板时(推荐)。
-
选择映射模板,然后执行以下操作:
-
选择添加映射模板。
-
对于内容类型,输入
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])
此映射模板使用字符串
pets
覆盖header1
,并创建一个名为$header3Value
的多值标头,该标头将header1
和header2
组合在一起。
-
-
选择保存。
-
选择测试选项卡。
-
在标头下,复制以下代码:
header1:header1Val header2:header2Val
-
选择 Test (测试)。
在日志中,您应看到一个包含此文本的条目:
Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, header1=pets, x-amzn-apigateway-api-id=
api-id
, Accept=application/json, multivalueheader=pets,header1Valheader2Val}
- AWS CloudFormation
-
在此示例中,您使用 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
变量的列表,请参阅数据转换的上下文变量。