Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用 API Gateway 控制台设置请求和响应数据映射

要使用 API Gateway 控制台定义 API 的集成请求/响应,请按照以下说明操作。

注意

这些说明假设您已完成 使用 API Gateway 控制台设置 API 集成请求 中的步骤。

  1. 资源窗格中选定方法的情况下,在 Method Execution (方法执行) 窗格中,选择 Integration Request (集成请求)

  2. 对于 HTTP 代理或 AWS 服务代理,要将集成请求中定义的路径参数、查询字符串参数或标头参数与 HTTP 代理或 AWS 服务代理的方法请求中对应的路径参数、查询字符串参数或标头参数进行关联,请执行以下操作:

    1. 分别选择 URL Path Parameters (URL 路径参数)URL Query String Parameters (URL 查询字符串参数)HTTP Headers (HTTP 标头) 旁边的箭头,然后分别选择 Add path (添加路径)Add query string (添加查询字符串)Add header (添加标头)

    2. 对于名称,键入 HTTP 代理或 AWS 服务代理中的路径参数、查询字符串参数或标头参数的名称。

    3. 对于 Mapped from (映射来源),键入路径参数、查询字符串参数或标头参数的映射值。使用以下格式之一:

      • method.request.path.parameter-name 用于名为 parameter-name 的路径参数,如 Method Request (方法请求) 页面所定义。

      • method.request.querystring.parameter-name 用于名为 parameter-name 的查询字符串参数,如 Method Request (方法请求) 页面所定义。

      • method.request.multivaluequerystring.parameter-name 用于名为 parameter-name 的多值查询字符串参数,如 Method Request (方法请求) 页面所定义。

      • method.request.header.parameter-name 用于名为 parameter-name 的标头参数,如 Method Request (方法请求) 页面所定义。

        或者,您可以将一个文字字符串值(用单引号引起)设置为集成标头。

      • method.request.multivalueheader.parameter-name 用于名为 parameter-name 的多值标头参数,如 Method Request (方法请求) 页面所定义。

    4. 选择 Create。(要删除路径参数、查询字符串参数或标头参数,请选择要删除的参数旁边的取消删除。)

  3. Body Mapping Templates (正文映射模板) 区域中,为 Request body passthrough (请求正文传递) 选择一个选项,以配置如何将未映射内容类型的方法请求正文通过集成请求传递至 Lambda 函数、HTTP 代理或 AWS 服务代理而不进行转换。这里有三个选项:

    • 如果您希望在方法请求内容类型不匹配任何与映射模板关联的内容类型时,将方法请求正文通过集成请求发送到后端而不进行转换(如下一步所定义),则选择 When no template matches the request Content-Type header (当没有模板匹配请求的 Content-Type 标头时)

      注意

      调用 API Gateway API 时,您通过将 WHEN_NO_MATCH 设置为集成资源的 passthroughBehavior 属性值来选择此选项。

    • 如果您希望在集成请求中未定义映射模板时,将方法请求正文通过集成请求发送到后端而不进行转换,则选择 When there are no templates defined (recommended) (当未定义模板时(推荐))。如果选择此选项时定义了模板,则会以“HTTP 415 Unsupported Media Type”响应拒绝未映射内容类型的方法请求。

      注意

      调用 API Gateway API 时,您通过将 WHEN_NO_TEMPLATE 设置为集成资源的 passthroughBehavior 属性值来选择此选项。

    • 如果您不希望在任一方法请求内容类型与集成请求中定义的映射模板关联的任何内容类型均不匹配时或者集成请求中未定义映射模板时传递方法请求,则选择 Never (永不)。将以“HTTP 415 Unsupported Media Type”响应拒绝未映射内容类型的方法请求。

      注意

      调用 API Gateway API 时,您通过将 NEVER 设置为集成资源的 passthroughBehavior 属性值来选择此选项。

    有关集成传递行为的更多信息,请参阅集成传递行为

  4. 要定义传入请求的映射模板,选择 Content-Type (内容-类型) 下的 Add mapping template (添加映射模板)。在输入文本框中键入一种内容类型(例如 application/json),然后选择复选标记图标以保存输入。然后,手动键入映射模板,或从模型模板中选择 Generate template (生成模板) 以创建模板。有关更多信息,请参阅 为请求和响应映射创建模型和映射模板

  5. 您可以将集成响应从后端映射到返回给调用应用程序的 API 的方法响应。这包括向客户端返回从后端可用的响应标头中选择的响应标头,从而将后端响应负载的数据格式转换为 API 指定的格式。您可以通过从 Method Execution (方法执行) 页面配置 Method Response (方法响应)Integration Response (集成响应) 来指定此类映射。

    1. Method Execution (方法执行) 窗格中,选择 Integration Response (集成响应)。选择 200 旁边的箭头以便为方法中的 200 HTTP 响应代码指定设置,或选择 Add integration response (添加集成响应) 以便为方法中的任何其他 HTTP 响应状态代码指定设置。

    2. 对于 Lambda error regex (&LAM; 错误正则表达式)(针对 Lambda 函数)或 HTTP status regex (HTTP 状态正则表达式)(针对 HTTP 代理或 AWS 服务代理),请键入正则表达式以指定哪些 Lambda 函数错误字符串 (针对 Lambda 函数) 或 HTTP 响应状态代码 (针对 HTTP 代理或 AWS 服务代理) 映射到此输出映射。例如,要将所有 2xx HTTP 响应状态代码从 HTTP 代理映射到此输出映射,请为 HTTP status regex (HTTP 状态正则表达式) 键入“2\\d{2}”。要将一条包含“Invalid Request”(无效请求)的错误消息从 Lambda 函数返回给 400 Bad Request 响应,请键入“.*Invalid request.*”作为 Lambda error regex 表达式。另一方面,要对 Lambda 中的所有未映射错误消息返回 400 Bad Request,请在 Lambda error regex 中键入“(\n|.)+”。这最后一个正则表达式可用于 API 的默认错误响应。

      注意

      API Gateway 使用 Java 模式的正则表达式来响应映射。有关更多信息,请参阅 Oracle 文档中的模式

      错误模式与 Lambda 响应中的 errorMessage 属性(在 Node.js 中由 callback(errorMessage) 填充,或在 Java 中由 throw new MyException(errorMessage) 填充)的整个字符串匹配。此外,在应用正则表达式之前,转义字符将不会转义。

      如果您使用.+' 作为选择模式来筛选响应,请注意,它可能与包含换行符 (“\n”) 的响应不匹配。

    3. 如果启用,对于 Method response status (方法响应状态),选择您在 Method Response (方法响应) 页面中定义的 HTTP 响应状态代码。

    4. 对于 Header Mappings (标头映射),针对您在 Method Response (方法响应) 页面中定义的 HTTP 响应状态代码的每个标头,请通过选择编辑来指定映射值。对于 Mapping value (映射值),请使用以下格式之一:

      • integration.response.multivalueheaders.header-name 格式,其中 header-name 是来自后端的多值响应标头的名称。

        例如,要将后端响应的 Date 标头作为 API 方法响应的 Timestamp 标头返回,Response header (映射) 列将包含一个 Timestamp (时间戳) 条目并且关联的 Mapping value (映射值) 应设置为 integration.response.multivalueheaders.Date

      • integration.response.header.header-name 格式,其中 header-name 是来自后端的多值响应标头的名称。

        例如,要将后端响应的 Date 标头作为 API 方法响应的 Timestamp 标头返回,Response header (响应标头) 列将包含一个 Timestamp (时间戳) 条目并且关联的 Mapping value (映射值) 应设置为 integration.response.header.Date

    5. Template Mappings (模板映射) 区域中,在 Content type (内容类型) 的旁边,选择添加。在 Content type (内容类型) 框中,键入将从 Lambda 函数、HTTP 代理或 AWS 服务代理传递至该方法的数据的内容类型。选择 Update

    6. 如果您希望该方法接收但不修改 Lambda 函数、HTTP 代理或 AWS 服务代理的数据,则选择 Output passthrough (输出传递)

    7. 如果已清除 Output passthrough (输出传递),则对于 Output mapping (输出映射),指定您希望 Lambda 函数、HTTP 代理或 AWS 服务代理用于将数据发送到该方法的输出映射模板。您可以手动键入映射模板,也可以从 Generate template from model (从模型中生成模板) 中选择模型。

    8. 选择 Save (保存)