使用映射模板覆盖 API 的请求和响应参数以及状态代码
利用标准 API Gateway 参数和响应代码映射模板,您可以一对一地映射参数,并将一系列集成响应状态代码(由正则表达式匹配)映射到单个响应状态代码。映射模板覆盖使您能够灵活地执行多对一参数映射;在应用标准 API Gateway 映射后覆盖参数;根据正文内容或其他参数值有条件地映射参数;通过编程方式动态地创建新的参数;并覆盖由集成终端节点返回的状态代码。可覆盖任何类型的请求参数、响应标头或响应状态代码。
以下是用于映射模板覆盖的示例:
-
创建新的标头(或覆盖现有标头)作为两个参数的联接
-
根据正文内容覆盖响应代码以获得成功或失败代码
-
根据一个参数的内容或其他参数的内容有条件地重新映射该参数
-
循环访问 JSON 正文的内容并将密钥值对重新映射到标头或查询字符串
要创建映射模板覆盖,请映射模板中一个或多个以下的 $context 变量:
请求正文映射模板 | 响应正文映射模板 |
---|---|
$context.requestOverride.header. |
$context.responseOverride.header. |
$context.requestOverride.path. |
$context.responseOverride.status |
$context.requestOverride.querystring. |
注意
映射模板覆盖不能与代理集成终端节点(它们缺少数据映射)结合使用。有关集成类型的更多信息,请参阅选择 API Gateway API 集成类型。
重要
覆盖是最终的。对于每个参数,覆盖只能应用一次。多次尝试覆盖同一个参数将导致来自 Amazon API Gateway 的 5XX
响应。如果您必须在整个模板中多次覆盖相同的参数,我们建议创建一个变量并在模板末尾应用覆盖。请注意,仅在解析整个模板后应用模板。请参阅教程:使用 API Gateway 控制台覆盖 API 的请求参数和标头。
以下教程介绍如何在 API Gateway 控制台中创建和测试映射模板覆盖。这些教程使用 PetStore 示例 API 作为起点。这两个教程都假定您已创建 PetStore 示例 API。
主题
教程:使用 API Gateway 控制台覆盖 API 的响应状态代码
要使用 PetStore 示例 API 检索宠物,您使用 GET /pets/{petId}
的 API 方法请求,其中 {petId}
是可在运行时获取数字的路径参数。
在本教程中,您将通过创建映射模板(此模板在检测到错误条件时,将 $context.responseOverride.status
映射到 400
)来覆盖此 GET
方法的响应代码。
通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway
。 -
在 API 下,选择 PetStore API。
-
在 Resources (资源) 列中,选择
GET
下的/{petId}
方法。 -
在 Client (客户端) 框中,选择 Test (测试)。
-
为 {petId} 键入
-1
,并选择 Test (测试)。在结果中,您会发现两件事:
首先,Response Body (响应正文) 表示超出范围错误:
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }
其次,Logs (日志) 框下的最后一行的结尾为:
Method completed with status: 200
。 -
返回到 Method Execution (方法执行)。选择 Integration Response (集成响应),然后选择 200 旁边的箭头。
-
在 Mapping Templates (映射模板) 部分中,选择 Add mapping template (添加映射模板)。
-
对于内容类型,键入
application/json
,然后选择对勾图标以保存设置。 -
将以下代码复制到模板区域中:
#set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end
-
选择 Save。
-
返回到 Method Execution (方法执行)。
-
在 Client (客户端) 框中,选择 Test (测试)。
-
为 {petId} 键入
-1
,并选择 Test (测试)。在结果中,Response Body (响应正文) 表示超出范围错误:
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }
不过,Logs (日志) 框下的最后一行现在的结尾为:
Method completed with status: 400
。
教程:使用 API Gateway 控制台覆盖 API 的请求参数和标头
在本教程中,您将通过创建映射模板(此模板将 $context.requestOverride.header.
映射到一个组合其他两个标头的新标头)来覆盖 header_name
GET
方法的请求标头。
通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway
。 -
在 API 下,选择 PetStore API。
-
在 Resources (资源) 列中,选择
GET
下的/pets
方法。 -
选择 Method Request (方法请求)。
-
创建如下所示的参数:
-
展开 HTTP Request Headers (HTTP 请求标头)。
-
选择 Add header (添加标头)。
-
在 Name (名称)下方,键入
header1
。 -
选择对勾图标以保存您的选择。
重复此过程以创建名为
header2
的第二个标题。 -
-
返回到 Method Execution (方法执行)。
-
选择 Integration Request (集成请求)。
-
展开 HTTP Headers (HTTP 标头)。您将看到您创建的两个标头(即
header1
和header2
)及其默认映射(在 Mapped from (映射自)下)。 -
展开 Mapping Templates (映射模板)。
-
选择 Add mapping template (添加映射模板)。
-
对于内容类型,键入
application/json
,然后选择对勾图标以保存设置。 -
将显示一个弹出窗口,指示 Note: This template can map headers and body (注意: 此模板可以映射标头和正文)。
选择 Yes, secure this integration (是,锁定此集成)。
-
将以下代码复制到模板区域中:
#set($header1Override = "foo") #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])
-
选择 Save。
-
返回到 Method Execution (方法执行)。
-
在 Client (客户端) 框中,选择 Test (测试)。
-
在 {pets} 的 Headers (标头) 下,复制以下代码:
header1:header1Val header2:header2Val
-
选择 Test (测试)。
在日志中,您应看到一个包含此文本的条目:
Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, header1=foo, x-amzn-apigateway-api-id=
<api-id>
, Accept=application/json, multivalueheader=foo,header1Valheader2Val}
示例:使用 API Gateway CLI 覆盖 API 的请求参数和标头
以下 CLI 示例说明如何使用 put-integration
命令来覆盖响应代码:
aws apigateway put-integration --rest-api-id
<API_ID>
--resource-id<PATH_TO_RESOURCE_ID>
--http-method<METHOD>
--type<INTEGRATION_TYPE>
--request-templates<REQUEST_TEMPLATE_MAP>
其中,<REQUEST_TEMPLATE_MAP>
是从内容类型到要应用的模板字符串的映射。此映射的结构如下所示:
Content_type1=template_string,Content_type2=template_string
或,在 JSON 语法中:
{"content_type1": "template_string" ...}
以下示例说明如何使用 put-integration-response
命令来覆盖 API 的响应代码:
aws apigateway put-integration-response --rest-api-id
<API_ID>
--resource-id<PATH_TO_RESOURCE_ID>
--http-method<METHOD>
--status-code<STATUS_CODE>
--response-templates<RESPONSE_TEMPLATE_MAP>
其中,<RESPONSE_TEMPLATE_MAP>
与上述的<REQUEST_TEMPLATE_MAP>
具有相同格式。
示例:使用适用于 JavaScript 的开发工具包覆盖 API 的请求参数和标头
以下示例说明如何使用 put-integration
命令来覆盖响应代码:
请求:
var params = { httpMethod: 'STRING_VALUE', /* required */ resourceId: 'STRING_VALUE', /* required */ restApiId: 'STRING_VALUE', /* required */ type: HTTP | AWS | MOCK | HTTP_PROXY | AWS_PROXY, /* required */ requestTemplates: { '
<Content_type>
': 'TEMPLATE_STRING', /* '<String>
': ... */ }, }; apigateway.putIntegration(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });
响应:
var params = { httpMethod: 'STRING_VALUE', /* required */ resourceId: 'STRING_VALUE', /* required */ restApiId: 'STRING_VALUE', /* required */ statusCode: 'STRING_VALUE', /* required */ responseTemplates: { '<Content_type>': 'TEMPLATE_STRING', /* '<String>': ... */ }, }; apigateway.putIntegrationResponse(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });