# 针对 API Gateway 中 REST API 的网关响应
<a name="api-gateway-gatewayResponse-definition"></a>

 网关响应使用 API Gateway 定义的响应类型进行标识。响应由 HTTP 状态代码（这是一组由参数映射指定的额外标头）和由非 [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html) 映射模板生成的有效载荷组成。

 在 API Gateway REST API 中，[GatewayResponse](https://docs.amazonaws.cn/apigateway/latest/api/API_GatewayResponse.html) 表示网关响应。在 OpenAPI 中，[x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) 扩展表示 `GatewayResponse` 实例。

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

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

## 设置网关响应以自定义错误响应
<a name="customize-gateway-responses"></a>

如果 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` 变量的更多信息，请参阅 [数据转换的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)。有关 `$stageVariables` 的更多信息，请参阅[阶段变量](api-gateway-mapping-template-reference.md#stagevariables-template-reference)。有关方法请求参数的更多信息，请参阅 [输入变量](api-gateway-mapping-template-reference.md#input-variable-reference)。

**Topics**
+ [设置网关响应以自定义错误响应](#customize-gateway-responses)
+ [使用 API Gateway 控制台为 REST API 设置网关响应](set-up-gateway-response-using-the-console.md)
+ [使用 API Gateway REST API 设置网关响应](set-up-gateway-response-using-the-api.md)
+ [在 OpenAPI 中设置网关响应自定义](set-up-gateway-responses-in-swagger.md)
+ [API Gateway 的网关响应类型](supported-gateway-response-types.md)