API Gateway 中的网关响应 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

API Gateway 中的网关响应

网关响应使用 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 在外部交换和 Amazon 云之间提供协调时,您可以使用集成请求或集成响应的 VTL 映射模板将负载从一种格式映射到另一种格式。但是,VTL 映射模板仅适用于能够成功响应的有效请求。

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

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

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