针对 API Gateway 中 REST API 的网关响应

网关响应使用 API Gateway 定义的响应类型进行标识。响应由 HTTP 状态代码 (这是一组由参数映射指定的额外标头) 和由非 VTL 映射模板生成的负载组成。

在 API Gateway REST API 中，GatewayResponse 表示网关响应。在 OpenAPI 中，x-amazon-apigateway-gateway-responses.gatewayResponse 扩展表示 GatewayResponse 实例。

要启用网关响应，您需要在 API 级别为受支持的响应类型设置网关响应。每当 API Gateway 返回该类型的响应时，都将使用在网关响应中定义的标头映射和负载映射模板，以将映射结果返回 API 调用方。

下一节我们将介绍如何使用 API Gateway 控制台和 API Gateway REST API 设置网关响应。

设置网关响应以自定义错误响应

如果 API Gateway 无法处理某个传入请求，它会向客户端返回一个错误响应，而不会将请求转发到集成后端。默认情况下，错误响应会包含一个简短的描述性错误消息。例如，如果您尝试对未定义的 API 资源调用操作，您将收到一个显示 { "message": "Missing Authentication Token" } 消息的错误响应。如果首次使用 API Gateway，您可能会发现很难找到真正的问题。

对于某些错误响应，API Gateway 允许 API 开发人员通过自定义返回不同格式的响应。对于 Missing Authentication Token 示例，您可以为原始响应负载添加提示标注可能的原因，如下例所示：{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}。

当您的 API 在外部交换和 AWS 云之间提供协调时，您可以使用集成请求或集成响应的 VTL 映射模板将负载从一种格式映射到另一种格式。但是，VTL 映射模板仅适用于能够成功响应的有效请求。

对于无效请求，API Gateway 可以完全绕过该集成，返回错误响应。您必须通过自定义，以可支持交换的格式发出错误响应。此时，使用仅支持简单变量替换的非 VTL 映射模板进行自定义。

将 API Gateway 生成的错误响应泛化处理成由 API Gateway 生成的任何响应，我们将它们称为网关响应。以此区分 API Gateway 生成的响应与集成响应。网关响应映射模板能以 $context 的形式访问 $stageVariables 变量值和 method.request.param-position.param-name 属性值以及方法请求参数。

有关 $context 变量的更多信息，请参阅 适用于数据模型、授权方、映射模板和 CloudWatch 访问日志记录的 $context 变量。有关 $stageVariables 的更多信息，请参阅 $stageVariables。有关方法请求参数的更多信息，请参阅 $input 变量。