# 优化 REST API 的性能 在您将 API 设置为可供调用之后，您可能会意识到需要对其进行优化以提高响应能力。API Gateway 提供了一些用于优化 API 的策略，例如响应缓存和负载压缩。在本节中，您可以了解如何启用这些功能。 **Topics** + [API Gateway 中针对 REST API 的缓存设置](api-gateway-caching.md) + [针对 API Gateway 中的 REST API 的负载压缩](api-gateway-gzip-compression-decompression.md) # API Gateway 中针对 REST API 的缓存设置 您可以在 API Gateway 中启用 API 缓存来缓存端点的响应。借助缓存，您可以减少向端点发起的调用数量，同时减少向 API 发出的请求的延迟。 为某个阶段启用缓存时，API Gateway 会在指定的生存时间 (TTL) 期间（以秒为单位）缓存来自端点的响应。然后，在响应请求时，API Gateway 会从缓存中查找端点响应，而不会向端点发出请求。API 缓存的默认 TTL 值为 300 秒。最大 TTL 值为 3600 秒。TTL = 0 表示缓存功能处于禁用状态。 **注意** 缓存是尽力而为。您可以使用 Amazon CloudWatch 中的 `CacheHitCount` 和 `CacheMissCount` 指标，以监控 API Gateway 从 API 缓存中提供的请求。 可缓存的响应的最大大小为 1048576 字节。缓存数据加密可能会增加缓存时的响应的大小。 这是一项符合 HIPAA 要求的服务。有关AWS、《1996 年健康保险可携性与责任法》(HIPAA) 以及使用AWS服务处理、存储和传输受保护的医疗信息 (PHI) 的更多信息，请参阅 [HIPAA 概述](https://aws.amazon.com/compliance/hipaa-compliance/)。 **重要** 为某个阶段启用缓存时，默认情况下，仅 `GET` 方法已启用缓存。这有助于确保您的 API 的安全性和可用性。您可以通过[覆盖方法设置](#override-api-gateway-stage-cache-for-method-cache)为其他方法启用缓存。 **重要** 缓存功能基于您选择的缓存大小按小时计费。缓存没有资格享受 AWS 免费套餐。有关更多信息，请参阅 [API Gateway 定价](https://aws.amazon.com/api-gateway/pricing/)。 ## 启用 Amazon API Gateway 缓存 在 API Gateway 中，您可以为特定阶段启用缓存。 启用缓存时，您必须选择一个缓存容量。一般而言，容量越大，性能越高，但成本也更高。有关支持的缓存大小，请参阅《API Gateway API 参考》**中的 [cacheClusterSize](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html#apigw-CreateStage-request-cacheClusterSize)。 API Gateway 通过创建专用的缓存实例来实现缓存功能。这一过程耗时最多 4 分钟。 API Gateway 通过删除现有缓存实例并重新创建一个具有修改后的容量的新实例来更改缓存容量。所有现有的缓存数据均将被删除。 **注意** 缓存容量会影响缓存实例的 CPU、内存和网络带宽。因此，缓存容量会影响缓存的性能。 API Gateway 建议您运行 10 分钟的负载测试，来验证缓存容量是否适用于您的工作负载。确保负载测试期间的流量能够反映生产流量。例如，包括流量增加、流量恒定和流量高峰。负载测试应包括缓存可提供的响应以及向缓存添加项的唯一响应。监控负载测试期间的延迟、4xx、5xx、缓存命中和缓存未命中指标。根据这些指标，按需调整缓存容量。有关负载测试的更多信息，请参阅[如何选择最佳 API Gateway 缓存容量以避免达到速率限制？](https://repost.aws/knowledge-center/api-gateway-cache-capacity) ------ #### [ AWS 管理控制台 ] 在 API Gateway 控制台中，您可以在**阶段**页面上配置缓存。您可以预调配阶段缓存，并指定默认的方法级缓存设置。如果您开启默认的方法级别缓存，则会为阶段上的所有 `GET` 方法开启方法级缓存，除非该方法具有方法覆盖。部署到阶段的任何其它 `GET` 方法都将具有方法级缓存。要为阶段的特定方法配置方法级缓存设置，可以使用方法覆盖。有关方法覆盖的更多信息，请参阅[覆盖方法级缓存的 API Gateway 阶段级缓存](#override-api-gateway-stage-cache-for-method-cache)。 **要为指定阶段配置 API 缓存，请执行以下操作：** 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 选择**阶段**。 1. 在 API 的**阶段**列表中，选择阶段。 1. 在**阶段详细信息**部分中，选择**编辑**。 1. 在**其它设置**下，对于**缓存设置**，开启**配置 API 缓存**。 这会为您的阶段预调配一个缓存集群。 1. 要为阶段激活缓存，请开启**默认方法级缓存**。 这将为阶段上的所有 `GET` 方法开启方法级别缓存。您部署到此阶段的任何其它 `GET` 方法都将具有方法级缓存。 **注意** 如果您有方法级缓存的现有设置，则更改默认的方法级缓存设置不会影响该现有设置。 ![\[开启预调配 API 缓存和默认方法级缓存。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/api-caching-stage-flow.png) 1. 选择**保存更改**。 ------ #### [ AWS CLI ] 以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令更新阶段以预置缓存，并为阶段上的所有 `GET` 方法启用方法级别的缓存： ``` aws apigateway update-stage \ --rest-api-id a1b2c3 \ --stage-name 'prod' \ --patch-operations file://patch.json ``` `patch.json` 的内容如下所示： ``` [ { "op": "replace", "path": "/cacheClusterEnabled", "value": "true" }, { "op": "replace", "path": "/cacheClusterSize", "value": "0.5" }, { "op": "replace", "path": "/*/*/caching/enabled", "value": "true" } ] ``` **注意** 如果您有方法级缓存的现有设置，则更改默认的方法级缓存设置不会影响该现有设置。 ------ **注意** API Gateway 大约需要 4 分钟来完成对缓存的创建或删除。 创建缓存后，**缓存集群**值会从 `Create in progress` 变为 `Active`。完成缓存删除后，**缓存集群**值会从 `Delete in progress` 变为 `Inactive`。 当您为阶段上的所有方法开启方法级缓存时，**默认方法级缓存**值将变为 `Active`。如果您为阶段上的所有方法关闭方法级缓存，**默认方法级缓存**值将变为 `Inactive`。如果您有方法级缓存的现有设置，则更改缓存的状态不会影响该设置。 当您在阶段的**缓存设置**中启用缓存时，仅对 `GET` 方法进行缓存。要确保您的 API 的安全性和可用性，我们建议您不要更改此设置。不过，您可以通过 [覆盖方法设置](#override-api-gateway-stage-cache-for-method-cache) 为其他方法启用缓存。 如果想要验证缓存是否按预期正常运行，您有两种常规选择： + 针对您的 API 和阶段，检查 **CacheHitCount** 和 **CacheMissCount** 的 CloudWatch 指标。 + 在响应中放置一个时间戳。 **注意** 请不要使用来自 CloudFront 响应的 `X-Cache` 标头，来确定您的 API 是否由 API Gateway 缓存实例提供服务。 ## 覆盖方法级缓存的 API Gateway 阶段级缓存 您可以通过为特定方法开启或关闭缓存来覆盖阶段级缓存设置。您还可以修改 TTL 期间，或者为缓存的响应开启或关闭加密。 如果您预计正缓存的方法会在其响应中接收敏感数据，请加密缓存数据。为遵守各种合规性框架，您可能需要执行此操作。有关更多信息，请参阅《AWS Security Hub User Guide》**中的 [Amazon API Gateway Controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)。 ------ #### [ AWS 管理控制台 ] 如果您在**阶段详细信息**中更改默认方法级缓存设置，则不会影响具有覆盖功能的方法级缓存设置。 如果您预计某个进行缓存的方法将在其响应中接收敏感数据，请在**缓存设置**中选择**加密缓存数据**。 **要使用控制台为各个方法配置 API 缓存，请执行以下操作：** 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 选择 API。 1. 选择**阶段**。 1. 在 API 的**阶段**列表中，展开阶段，然后在 API 中选择方法。 1. 在**方法覆盖**部分，选择**编辑**。 1. 在**方法设置**部分，打开或关闭**启用方法缓存**或自定义任何其他所需选项。 **注意** 在您为阶段预调配缓存集群之前，缓存不会处于活动状态。 1. 选择**保存**。 ------ #### [ AWS CLI ] 以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令仅关闭 `GET /pets` 方法的缓存： ``` aws apigateway update-stage / --rest-api-id a1b2c3 / --stage-name 'prod' / --patch-operations file://patch.json ``` `patch.json` 的内容如下所示： ``` [{ "op": "replace", "path": "/~1pets/GET/caching/enabled", "value": "false" }] ``` ------ ## 将方法或集成参数用作索引缓存响应的缓存键 可以将方法或集成参数用作缓存键来对缓存的响应编制索引。这包括自定义标头、URL 路径或查询字符串。可以将这些参数中的一部分或全部指定为缓存键，但必须至少指定一个值。当您有缓存键时，API Gateway 会分别缓存来自每个键值的响应，包括缓存键不存在的情况。 **注意** 在资源上设置缓存时需要缓存键。 例如，假设您在以下格式中提出一个请求： ``` GET /users?type=... HTTP/1.1 host: example.com ... ``` 在这个请求中，`type` 的值可以是 `admin` 或 `regular`。如果您添加 `type` 参数作为缓存键的组成部分，则 `GET /users?type=admin` 的响应将与 `GET /users?type=regular` 的响应分开缓存。 当某种方法或集成请求采用多个参数时，您可以选择添加部分或全部参数来创建缓存键。例如，对于在 TTL 期内按列出的顺序提出的以下请求，您可以在缓存键中只添加 `type` 参数： ``` GET /users?type=admin&department=A HTTP/1.1 host: example.com ... ``` 此请求的响应将被缓存，并用于服务以下请求： ``` GET /users?type=admin&department=B HTTP/1.1 host: example.com ... ``` ------ #### [ AWS 管理控制台 ] 要在 API Gateway 控制台中将一个方法或集成请求参数添加为缓存键的一部分，请在添加参数后选择**缓存**。 ![\[将方法或集成参数添加为索引缓存响应的缓存键\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/api-caching-including-parameter-as-cache-key-new-console.png) ------ #### [ AWS CLI ] 以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令创建 `GET` 方法，并且需要 `type` 查询字符串参数： ``` aws apigateway put-method / --rest-api-id a1b2c3 / --resource-id aaa111 / --http-method GET / --authorization-type "NONE" / --request-parameters "method.request.querystring.type=true" ``` 以下 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 命令对 HTTP 端点创建 `GET` 方法的集成，并指定 API Gateway 来缓存 `type` 方法请求参数： ``` aws apigateway put-integration / --rest-api-id a1b2c3 / --resource-id aaa111 / --http-method GET / --type HTTP / --integration-http-method GET / --uri 'https://example.com' / --cache-key-parameters "method.request.querystring.type" ``` 要指定 API Gateway 来缓存集成请求参数，请使用 `integration.request.location.name` 作为缓存密钥参数。 ------ ## 刷新 API Gateway 中的 API 阶段缓存 启用 API 缓存时，您可以刷新 API 阶段的整个缓存，以确保您的 API 客户端可以从集成端点获得最新响应。 ------ #### [ AWS 管理控制台 ] **刷新 API 阶段缓存** 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 选择其阶段带有缓存的 API。 1. 在主导航窗格中，选择**阶段**，然后选择带有缓存的阶段。 1. 选择**阶段操作**菜单，然后选择**刷新阶段缓存**。 ------ #### [ AWS CLI ] 使用以下 [flush-stage-cache](https://docs.aws.amazon.com/cli/latest/reference/apigateway/flush-stage-cache.html) 命令刷新阶段缓存： ``` aws apigateway flush-stage-cache \ --rest-api-id a1b2c3 \ --stage-name prod ``` ------ **注意** 刷新缓存之后，在重新构建缓存之前，从集成端点为响应提供服务。在此期间，发送到集成端点的请求数量可能会增加。这可能会临时增加 API 的整体延迟。 ## 使 API Gateway 缓存条目失效 您的 API 客户端可以使某个现有缓存条目失效，也可以从各个请求的集成端点重新加载该条目。客户端必须发送一个包含 `Cache-Control: max-age=0` 标头的请求。客户端将直接从集成端点 (而非缓存) 收到响应，前提是客户端获得授权执行此操作。这会将现有缓存条目替换为从集成端点获得的新响应。 要为客户端授予权限，请将以下格式的策略附加到用户的 IAM 执行角色。 **注意** 不支持跨账户缓存无效化。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:InvalidateCache" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/stage-name/GET/resource-path-specifier" ] } ] } ``` ------ 此策略允许 API Gateway 执行服务让指定资源上的请求对应的缓存失效。要指定一组目标资源，请将 `account-id` 的 ARN 值中的 `api-id`、`Resource` 和其他条目替换为通配符 (\$1)。有关如何为 API Gateway 执行服务设置权限的更多信息，请参阅[使用 IAM 权限控制对 REST API 的访问](permissions.md)。 如果您未应用 `InvalidateCache` 策略（或在控制台中选中**需要授权**复选框），则任何客户端均可使 API 缓存失效。如果大部分或全部客户端都使 API 缓存失效，这会显著增加 API 的延迟。 策略到位后，将启用缓存并需要授权。 您可以在以下选项中选择 API Gateway 如何处理未经授权的请求： **使请求失败，返回 403 状态代码** API Gateway 返回 `403 Unauthorized` 响应。 要使用 API 设置该选项，请使用 `FAIL_WITH_403`。 **忽略缓存控制标头；在响应标头中添加警告** API Gateway 处理请求并在响应中添加警告标头。 要使用 API 设置该选项，请使用 `SUCCEED_WITH_RESPONSE_HEADER`。 **忽略缓存控制标头** API Gateway 处理请求，但不在响应中添加警告标头。 要使用 API 设置该选项，请使用 `SUCCEED_WITHOUT_RESPONSE_HEADER`。 您可以使用 API Gateway 控制台或 AWS CLI，针对未经授权的请求来设置处理行为。 ------ #### [ AWS 管理控制台 ] **指定如何处理未经授权的请求** 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 选择其阶段带有缓存的 API。 1. 在主导航窗格中，选择**阶段**，然后选择带有缓存的阶段。 1. 对于**阶段详细信息**，请选择**编辑**。 1. 对于**未经授权的请求处理**，选择一个选项。 1. 选择**继续**。 1. 预览更改，然后选择**保存更改**。 ------ #### [ AWS CLI ] 以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令可以更新阶段，将其处理未经授权请求的方式设置为使请求失败，并返回 403 状态代码： ``` aws apigateway update-stage / --rest-api-id a1b2c3 / --stage-name 'prod' / --patch-operations 'op=replace,path=/*/*/caching/unauthorizedCacheControlHeaderStrategy,value="FAIL_WITH_403"' ``` ------ ## 带有缓存的阶段的 CloudFormation 示例 以下 CloudFormation 模板创建示例 API，为 `Prod` 阶段预置 `0.5` GB 的缓存，并为所有 `GET` 方法启用方法级别的缓存。 **重要** 缓存功能基于您选择的缓存大小按小时计费。缓存没有资格享受 AWS 免费套餐。有关更多信息，请参阅 [API Gateway 定价](https://aws.amazon.com/api-gateway/pricing/)。 ### 示例 CloudFormation 模板 ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: cache-example PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: true AuthorizationType: NONE Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api ApiStage: Type: 'AWS::ApiGateway::Stage' Properties: StageName: Prod Description: Prod Stage with a cache RestApiId: !Ref Api DeploymentId: !Ref ApiDeployment CacheClusterEnabled: True CacheClusterSize: 0.5 MethodSettings: - ResourcePath: /* HttpMethod: '*' CachingEnabled: True ``` # 针对 API Gateway 中的 REST API 的负载压缩 API Gateway 允许您的客户端使用[支持的内容编码](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)之一调用具有压缩负载的 API。默认情况下，API Gateway 支持解压缩方法请求负载。但是，您必须配置 API 以启用方法响应负载的压缩。 要在 [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 上启用压缩，请在创建 API 时或在创建 API 之后，将 [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize) 属性设置为介于 0 到 10485760（10M 字节）之间的非负整数。要在 API 上禁用压缩，请将 `minimumCompressionSize` 设置为空值或者将属性与值一起删除。您可以使用 API Gateway 控制台、AWS CLI 或 API Gateway REST API 为 API 启用或禁用 API 压缩。 如果您希望在任意大小的负载上应用压缩，请将 `minimumCompressionSize` 值设置为零。不过，压缩较小大小的数据实际上可能会增加最终数据大小。此外，API Gateway 中的压缩和客户端中的解压缩可能会增加总体延迟并需要更多的计算时间。您应该根据 API 运行测试用例，确定最佳值。 客户端可以针对 API Gateway 提交具有压缩负载及合适 `Content-Encoding` 标头的 API 请求，以解压缩并应用适用的映射模板，然后再将请求传递到集成端点。启用解压缩并部署了 API 之后，如果在方法请求中指定了合适的 `Accept-Encoding` 标头，客户端可以接收具有压缩负载的 API 响应。 当集成端点预期并返回了未压缩的 JSON 负载时，为未压缩 JSON 负载配置的任何映射模板适用于压缩负载。对于压缩方法请求负载，API Gateway 解压缩负载，应用映射模板，然后将映射的请求传递到集成端点。对于未压缩的集成响应负载，API Gateway 应用映射模板，压缩映射的负载，并将压缩的负载返回客户端。 **Topics** + [在 API Gateway 中为 API 启用负载压缩](api-gateway-enable-compression.md) + [在 API Gateway 中使用压缩负载调用 API 方法](api-gateway-make-request-with-compressed-payload.md) + [接收 API Gateway 中具有压缩负载的 API 响应](api-gateway-receive-response-with-compressed-payload.md) # 在 API Gateway 中为 API 启用负载压缩 您可以使用 API Gateway 控制台、AWS CLI 或AWS开发工具包为 API 启用压缩。 对于现有 API，您必须在启用压缩后部署 API，这样更改才能生效。对于新 API，您可以在 API 设置完成后部署该 API。 **注意** 最高优先级内容编码必须是 API Gateway 支持的编码。如果不是，将不对响应负载应用压缩。 **Topics** + [使用 API Gateway 控制台为 API 启用负载压缩](#api-gateway-enable-compression-console) + [使用 AWS CLI 为 API 启用负载压缩](#api-gateway-enable-compression-cli) + [API Gateway 支持的内容编码](#api-gateway-supported-content-encodings) ## 使用 API Gateway 控制台为 API 启用负载压缩 以下过程介绍如何为 API 启用负载压缩。 **使用 API Gateway 控制台启用负载压缩** 1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 选择现有 API 或者创建新 API。 1. 在主导航窗格中，选择 **API 设置**。 1. 在 **API 详细信息**部分中，选择**编辑**。 1. 开启**内容编码**以启用负载压缩。对于**最小正文大小**，为最小压缩大小输入数字（字节数）。要关闭压缩，请关闭**内容编码**选项。 1. 选择 **Save changes（保存更改）**。 ## 使用 AWS CLI 为 API 启用负载压缩 以下 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 命令创建具有有效载荷压缩的 API： ``` aws apigateway create-rest-api \ --name "My test API" \ --minimum-compression-size 0 ``` 以下 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 命令为现有 API 启用有效载荷压缩： ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value=0 ``` `minimumCompressionSize` 属性具有 0 到 10485760（10M 字节）之间的非负整数值。它可测量压缩阈值。如果负载大小小于该值，则不会对负载应用压缩或解压缩。将它设置为零允许对任何负载大小进行压缩。 以下 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 命令关闭有效载荷压缩： ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value= ``` 您也可以将 `value` 设置为空字符串 `""` 或在上一调用中忽略 `value` 属性。 ## API Gateway 支持的内容编码 API Gateway 支持以下内容编码： + `deflate` + `gzip` + `identity` 根据 [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4) 规范，API Gateway 还支持以下 `Accept-Encoding` 标头格式： + `Accept-Encoding:deflate,gzip` + `Accept-Encoding:` + `Accept-Encoding:*` + `Accept-Encoding:deflate;q=0.5,gzip;q=1.0` + `Accept-Encoding:gzip;q=1.0,identity;q=0.5,*;q=0` # 在 API Gateway 中使用压缩负载调用 API 方法 要使用压缩负载发出 API 请求，客户端必须使用[支持的内容编码](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)之一设置 `Content-Encoding` 标头。 假设您使用 API 客户端并希望调用 PetStore API 方法 (`POST /pets`)。不要使用以下 JSON 输出来调用方法： ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Length: ... { "type": "dog", "price": 249.99 } ``` 相反，您可以通过使用 GZIP 编码压缩的相同负载来调用方法： ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Encoding:gzip Content-Length: ... ���RPP*�,HU�RPJ�OW��e&���L,�,-y�j ``` API Gateway 收到请求时，它会验证是否支持指定的内容编码。然后，它尝试解压缩具有指定内容编码的负载。如果解压缩成功，它会将请求分派到集成端点。如果不支持指定的编码或者提供的负载未使用指定编码压缩，API Gateway 返回 `415 Unsupported Media Type` 错误响应。如果此错误在解压缩的早期阶段发生（尚未确定您的 API 和阶段），则此错误不会记录到 CloudWatch Logs。 # 接收 API Gateway 中具有压缩负载的 API 响应 在启用压缩的 API 上发出请求时，客户端可以指定具有 [支持内容编码](api-gateway-enable-compression.md#api-gateway-supported-content-encodings) 的 `Accept-Encoding` 标头，选择接收特定格式的压缩响应负载。 API Gateway 仅在满足以下条件时压缩响应负载： + 传入请求具有 `Accept-Encoding` 标头和支持的内容编码及格式。 **注意** 如果未设置标头，默认值为 `*`（在 [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4) 中定义）。在这种情况下，API Gateway 不会压缩有效负载。某些浏览器或客户端可能会为启用了压缩的请求自动添加 `Accept-Encoding` (例如 `Accept-Encoding:gzip, deflate, br`)。这会在 API Gateway 中启用负载压缩。如果没有对支持的 `Accept-Encoding` 标头值的明确规范，API Gateway 不会压缩负载。 + 在 API 上设置了 `minimumCompressionSize` 以启用压缩。 + 集成响应没有 `Content-Encoding` 标头。 + 集成响应负载的大小，在应用了适用的映射模板之后，大于或等于指定的 `minimumCompressionSize` 值。 API Gateway 在压缩负载之前，应用为集成响应配置的任意映射模板。如果集成响应包含 `Content-Encoding` 标头，API Gateway 假设集成响应负载已经压缩并跳过压缩处理。 以 PetStore API 示例及以下请求为例： ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept: application/json ``` 后端对具有未压缩 JSON 负载的请求的响应类似于以下内容： ``` 200 OK [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` 要将此输出作为压缩负载接收，您的 API 客户端可以按以下所示提交请求： ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept-Encoding:gzip ``` 客户端接收具有 `Content-Encoding` 标头和 GZIP 编码负载的响应，类似于以下内容： ``` 200 OK Content-Encoding:gzip ... ���RP� J�)JV �:P^IeA*������+(�L �X�YZ�ku0L0B7!9��C#�&����Y��a���^�X ``` 在压缩响应负载之后，只收取压缩后数据大小的数据传输费用。