针对 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 在外部交换和 Amazon 云之间提供协调时,您可以使用集成请求或集成响应的 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 变量。