本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
使用映射模板覆盖 API 的请求和响应参数以及状态代码
标准 API Gateway 参数和响应代码映射模板允许您映射参数 one-to-one 并将一系列集成响应状态码(由正则表达式匹配)映射到单个响应状态代码。映射模板覆盖使您可以灵活地执行 many-to-one参数映射;在应用标准 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 检索宠物,您可以使用的 API 方法请求GET /pets/{petId}
,其中{petId}
是一个路径参数,可以在运行时取一个数字。
在本教程中,您将通过创建映射模板(此模板在检测到错误条件时,将 $context.responseOverride.status
映射到 400
)来覆盖此 GET
方法的响应代码。
通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway
。 -
在 API 下,选择 PetStore API,然后选择资源。
-
在资源树中,选择
/{petId}
下的GET
方法。 选择测试选项卡。您可能需要选择右箭头按钮,以显示该选项卡。
-
对于 petId,输入
-1
,然后选择测试。在结果中,您会发现两件事:
首先,响应正文表示 out-of-range错误:
{ "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }
其次,日志框下的最后一行的结尾为:
Method completed with status: 200
。 -
在集成响应选项卡上,对于默认 - 响应,选择编辑。
-
选择映射模板。
-
选择 Add mapping template (添加映射模板)。
-
对于内容类型,输入
application/json
。 -
对于模板正文,输入以下内容:
#set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end
-
选择保存。
-
选择测试选项卡。
-
对于 petId,输入
-1
。 -
在结果中,响应正文表示存在 out-of-range 错误:
{ "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。
-
在资源树中,选择
/pet
下的GET
方法。 -
在方法请求选项卡上,对于方法请求设置,选择编辑。
-
选择 HTTP 请求标头,然后选择添加标头。
对于名称,请输入
header1
。-
选择添加标头,然后创建第二个标头,名为
header2
。 -
选择保存。
-
在集成请求选项卡上,对于集成请求设置,选择编辑。
对于请求正文传递,选择当未定义模板时(推荐)。
-
选择映射模板,然后执行以下操作:
选择 Add mapping template (添加映射模板)。
对于内容类型,输入
application/json
。对于模板正文,输入以下内容:
#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])
-
选择保存。
-
选择测试选项卡。
-
在 {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>
具有相同格式。
示例:使用 SDK 覆盖 API 的请求参数和标头 JavaScript
以下示例说明如何使用 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 });