Amazon API Gateway API 请求和响应数据映射参考 - Amazon API Gateway
将方法请求数据映射至集成请求参数将集成响应数据映射到方法响应标头在方法和集成之间映射请求和响应负载

Amazon API Gateway API 请求和响应数据映射参考

本节将说明如何设置从 API 的方法请求数据（包括存储在 context、stage 或 util 变量中的其他数据）到相应的集成请求参数，以及从包括其他数据在内的集成响应数据到方法响应参数的数据映射。方法请求数据包括请求参数（路径、查询字符串和标头）和正文。集成响应数据包括响应参数（标头）和正文。有关使用阶段变量的更多信息，请参阅 API Gateway 中的 REST API 的 API Gateway 阶段变量引用。

主题

将方法请求数据映射至集成请求参数

可从任何定义的方法请求参数和负载映射采用路径变量、查询字符串或标头形式的集成请求参数。

此处，PARAM_NAME 是给定参数类型的方法请求参数的名称。它必须匹配正则表达式 '^[a-zA-Z0-9._$-]+$]'。它必须经过定义才能被引用。JSONPath_EXPRESSION 是请求或响应正文的 JSON 字段的 JSONPath 表达式。

注意

此语法中省略了前缀 "$"。

映射的数据来源

映射表达式
方法请求路径 method.request.path.PARAM_NAME
方法请求查询字符串 method.request.querystring.PARAM_NAME
多值方法请求查询字符串 method.request.multivaluequerystring.PARAM_NAME
方法请求标头 method.request.header.PARAM_NAME
多值方法请求标头 method.request.multivalueheader.PARAM_NAME
方法请求正文 method.request.body
方法请求正文 (JsonPath) method.request.body.JSONPath_EXPRESSION.
阶段变量 stageVariables.VARIABLE_NAME
上下文变量 context.VARIABLE_NAME，必须为受支持的上下文变量之一。
静态值 'STATIC_VALUE'。STATIC_VALUE 为字符串文本值，必须括在一对单引号内。
例 从 OpenAPI 中的方法请求参数映射

下面的示例显示了一个 OpenAPI 代码段：

  • 将名为 methodRequestHeaderParam 的方法请求标头映射到名为 integrationPathParam 的集成请求路径参数

  • 将名为 methodRequestQueryParam 的多值方法请求查询字符串映射到名为 integrationQueryParam 的集成请求查询字符串


...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam"
            
}
...

还可以使用 JSONPath 表达式从 JSON 请求正文中的字段映射集成请求参数。下表显示了适用于方法请求正文及其 JSON 字段的映射表达式。

例 从 OpenAPI 中的方法请求正文映射

下面的示例显示了一个 OpenAPI 代码段，该代码段 1) 将方法请求正文映射到名为 body-header 的集成请求标头，以及 2) 该正文的某个 JSON 字段，由 JSON 表达式（petstore.pets[0].name，不带 $. 前缀）表示。


...
"requestParameters" : {
            
    "integration.request.header.body-header" : "method.request.body",
    "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name",
            
}
...

将集成响应数据映射到方法响应标头

可从任意集成响应标头或集成响应正文、$context 变量或静态值映射方法响应标头参数。下表描述了方法响应标头映射表达式。

映射的数据来源 映射表达式
集成响应标头 integration.response.header.PARAM_NAME
集成响应标头 integration.response.multivalueheader.PARAM_NAME
集成响应正文 integration.response.body
集成响应正文 (JsonPath) integration.response.body.JSONPath_EXPRESSION
阶段变量 stageVariables.VARIABLE_NAME
上下文变量 context.VARIABLE_NAME，必须为受支持的上下文变量之一。
静态值 'STATIC_VALUE'。STATIC_VALUE 为字符串文本值，必须括在一对单引号内。
例 从 OpenAPI 中的集成响应进行数据映射

下面的示例显示了一个 OpenAPI 代码段，该代码段 1) 将集成响应的 JSONPath 字段 redirect.url 映射到请求响应的 location 标头；并 2) 将集成响应的 x-app-id 标头映射到方法响应的 id 标头。


...
"responseParameters" : {
            
    "method.response.header.location" : "integration.response.body.redirect.url",
    "method.response.header.id" : "integration.response.header.x-app-id",
    "method.response.header.items" : "integration.response.multivalueheader.item",
            
}
...

在方法和集成之间映射请求和响应负载

API Gateway 使用 Velocity 模板语言 (VTL) 引擎来处理集成请求和集成响应的正文映射模板。映射模板将方法请求负载转换成相应的集成请求负载，并将集成响应正文转换成方法响应正文。

VTL 模板使用 JSONPath 表达式、调用上下文和阶段变量等其他参数，以及实用工具函数来处理 JSON 数据。

如果定义了一个模型来描述负载的数据结构，API Gateway 可以使用该模型为集成请求或集成响应生成骨骼映射模板。您可以使用该骨骼模板来辅助自定义和扩展映射 VTL 脚本。但是，您可以从头开始创建一个映射模板，而不为负载的数据结构定义模型。

选择 VTL 映射模板

API Gateway 使用以下逻辑选择 Velocity 模板语言 (VTL) 的映射模板，将负载从方法请求映射到相应的集成请求，或者将它从集成响应映射到相应的方法响应。

对于请求负载，API Gateway 将请求的 Content-Type 标头值作为密钥来选择请求负载的映射模板。对于响应负载，API Gateway 使用传入请求的 Accept 标头作为密钥来选择映射模板。

当请求中缺少 Content-Type 标头时，API Gateway 会假定其默认值为 application/json。对于此类请求，API Gateway 将使用 application/json 作为默认密钥来选择映射模板（如果已定义模板的话）。当没有模板与该密钥相匹配时， API Gateway 会在 passthroughBehavior 属性设置为 WHEN_NO_MATCH 或 WHEN_NO_TEMPLATES 时以非映射形式传递负载。

未在请求中指定 Accept 标头时，API Gateway 会假定其默认值为 application/json。在这种情况下，API Gateway 会选择 application/json 的现有映射模板映射响应负载。如果未对 application/json 定义任何模板，API Gateway 会选择第一个现有模板并将其用作默认模板来映射响应负载。类似地，当指定的 Accept 标头值不与任何现有的模板密钥匹配时，API Gateway 将使用第一个现有的模板。如果未定义任何模板，则 API Gateway 以非映射形式传递响应负载。

例如，假定 API 有一个为请求负载定义的 application/json 模板和一个为响应负载定义的 application/xml 模板。如果客户端设置了请求的 "Content-Type : application/json" 和 "Accept : application/xml" 标头，将使用相应的映射模板处理请求负载和响应负载。如果缺少 Accept:application/xml 标头，则将使用 application/xml 映射模板来映射响应负载。而要返回未映射的响应负载，则必须为 application/json 设置一个空模板。

选择映射模板时，仅从 Accept 和 Content-Type 标头中使用 MIME 类型。例如，"Content-Type: application/json; charset=UTF-8" 的标头将有一个已选择 application/json 密钥的请求模板。