使用 API Gateway 控制台设置请求和响应数据映射 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

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

注意

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

  1. 在资源窗格中，选择您的方法。

  2. 在集成请求选项卡的集成请求设置下，选择编辑。

  3. 为请求正文传递选择一个选项，以配置如何通过集成请求传递未映射内容类型的方法请求正文，而无需转换为 Lambda 函数、HTTP 代理或服务代理。 Amazon 这里有三个选项：

    • 如果您希望在方法请求内容类型不匹配任何与映射模板关联的内容类型时，将方法请求正文通过集成请求发送到后端而不进行转换（如下一步所定义），则选择当没有模板匹配请求的 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. 对于 HTTP 代理或 Amazon 服务代理，要将集成请求中定义的路径参数、查询字符串参数或标头参数与 HTTP 代理或 Amazon 服务代理的方法请求中的相应路径参数、查询字符串参数或标头参数相关联，请执行以下操作：

    1. 分别选择 URL 路径参数、URL 查询字符串参数或 HTTP 请求标头，然后分别选择添加路径、添加查询字符串或添加标头。

    2. 在 “名称” 中，键入 HTTP 代理或 Amazon 服务代理中的路径参数、查询字符串参数或标头参数的名称。

    3. 对于映射自，输入路径参数、查询字符串参数或标头参数的映射值。使用以下格式之一：

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

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

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

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

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

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

    4. 要添加其他参数，请选择添加按钮。

  5. 要添加映射模板，请选择映射模板。

  6. 要定义传入请求的映射模板，请选择添加映射模板。对于内容类型，输入一个内容类型（例如 application/json）。然后，手动输入映射模板，或从模型模板中选择生成模板以创建模板。有关更多信息，请参阅了解映射模板。

  7. 选择 Save（保存）。

  8. 您可以将集成响应从后端映射到返回给调用应用程序的 API 的方法响应。这包括向客户端返回从后端可用的响应标头中选择的响应标头，从而将后端响应负载的数据格式转换为 API 指定的格式。您可以配置方法响应和集成响应来指定此类映射。

    要让该方法接收基于 Lambda 函数、HTTP 代理或 Amazon 服务代理返回的 HTTP 状态码的自定义响应数据格式，请执行以下操作：

    1. 选择集成响应。选择默认 - 响应上的编辑，以便为方法中的 200 HTTP 响应代码指定设置，或选择创建响应，以便为方法中的任何其他 HTTP 响应状态代码指定设置。

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

      注意

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

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

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

    3. 如果启用，对于方法响应状态，选择您在方法响应页面上定义的 HTTP 响应状态代码。

    4. 对于标头映射，针对您在方法响应页面上为 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. 选择映射模板，然后选择添加映射模板。在内容类型框中，输入将从 Lambda 函数、HTTP 代理或 Amazon 服务代理传递到该方法的数据的内容类型。然后，手动输入映射模板，或从模型模板中选择生成模板以创建模板。有关更多信息，请参阅了解映射模板。

    6. 选择 Save（保存）。