本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 最佳化 REST API 的效能 讓您的 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 合格服務。如需 1996 年 AWS美國健康保險流通與責任法案 (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. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 選擇 **Stages** (階段)。 1. 在 API 的 **Stages** (階段) 清單中，選擇階段。 1. 在**階段詳細資訊**區段中，選擇**編輯**。 1. 在**其他設定**下，針對**快取設定**開啟 **API 快取**。 這會為您的階段佈建快取叢集。 1. 若要為您的階段啟用快取，請開啟**預設方法層級快取**。 這會開啟您的階段上所有 `GET` 方法的方法層級快取。您部署至此階段的其他任何 `GET` 方法，都會有方法層級快取。 **注意** 如果您有方法層級快取的現有設定，變更預設方法層級快取設定並不會影響現有設定。 ![\[開啟佈建 API 快取和預設方法層級快取。\]](http://docs.aws.amazon.com/zh_tw/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 與階段的 CloudWatch 指標 **CacheHitCount** 與 **CacheMissCount**。 + 將時間戳記放在回應中。 **注意** 請勿使用 CloudFront 回應中的 `X-Cache` 標頭，來判斷您的 API 是否由 API Gateway 快取執行個體所提供。 ## 覆寫方法層級快取的 API Gateway 階段層級快取 您可以開啟或關閉特定方法的快取，藉以覆寫階段層級快取設定。您也可以修改 TTL 期間，或開啟或關閉快取回應的加密功能。 如果您預期正在快取的方法會在其回應中收到敏感資料，請加密快取資料。您可能需要這樣做，才能符合各種合規架構。如需詳細資訊，請參閱《AWS Security Hub 使用者指南》**中的 [Amazon API Gateway 控制項](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)。 ------ #### [ AWS 管理主控台 ] 如果您在**階段詳細資訊**中變更預設方法層級快取設定，這並不影響具有覆寫權的方法層級快取設定。 如果您預期正在快取的方法會在其回應中收到敏感性資料，請在 **Cache Settings** (快取設定) 中，選擇 **Encrypt cache data** (加密快取資料)。 **使用主控台來設定個別方法的 API 快取：** 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 選擇 API。 1. 選擇 **Stages** (階段)。 1. 在 API 的 **Stages** (階段) 清單中，展開階段，然後在 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 主控台中包含方法或整合請求參數作為快取金鑰的一部分，請在新增參數之後選取 **Caching** (快取)。 ![\[包含方法或整合參數做為快取金鑰來編製快取回應的索引\]](http://docs.aws.amazon.com/zh_tw/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) 命令會建立 `GET` 方法與 HTTP 端點的整合，並指定 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. 在以下網址登入 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`、`api-id` 與 `Resource` 之 ARN 值中的其他項目使用萬用字元 (\$1)。如需如何設定 API Gateway 執行服務許可的詳細資訊，請參閱 [使用 IAM 許可權控制 REST API 的存取](permissions.md)。 如果您未強制執行 `InvalidateCache` 政策 (或在主控台中勾選 **Require authorization** (需要授權) 核取方塊)，則任何用戶端都可能使 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. 在以下網址登入 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 (一千萬個位元組) 之間的非負整數。若要停用 API 的壓縮功能，請將 `minimumCompressionSize` 設定為 Null 或將其完全移除。您可以使用 API Gateway 主控台、 或 API Gateway REST API AWS CLI來啟用或停用 API 的壓縮。 如果您想要對任何大小的承載套用壓縮功能，請將 `minimumCompressionSize` 值設定為零。不過，壓縮大小很小的資料實際上可能會增加最終資料大小。此外，在 API Gateway 壓縮與在用戶端解壓縮可能會增加整體延遲，而需要更多的運算時間。您應該對 API 執行測試案例來決定最佳值。 用戶端可以提交已壓縮承載並具有適當 `Content-Encoding` 標頭的 API 請求，讓 API Gateway 解壓縮並套用適用的對應範本，再將請求傳遞到整合端點。啟用壓縮功能並部署 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、 或 SDK 啟用 API 的 AWS 壓縮。 針對現有的 API，您必須在啟用壓縮後部署 API，以使變更生效。針對新的 API，您可以在 API 設定完成後部署 API。 **注意** 優先順序最高的內容編碼必須是 API Gateway 支援的項目，否則系統不會將壓縮功能套用至回應承載。 **Topics** + [使用 API Gateway 主控台啟用 API 的承載壓縮功能](#api-gateway-enable-compression-console) + [使用 啟用 API 的承載壓縮 AWS CLI](#api-gateway-enable-compression-cli) + [API Gateway 支援的內容編碼](#api-gateway-supported-content-encodings) ## 使用 API Gateway 主控台啟用 API 的承載壓縮功能 下列程序說明如何啟用 API 的承載壓縮功能。 **使用 API Gateway 主控台來啟用承載壓縮功能** 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 選擇現有的 API 或建立新的 API。 1. 在主導覽窗格中，選擇 **API 設定**。 1. 在 **API 詳細資訊**區段中，選擇**編輯**。 1. 開啟**內容編碼**以啟用承載壓縮。針對**內文大小下限**，輸入代表壓縮大小下限的數字 (位元組)。若要關閉壓縮，請關閉**內容編碼**選項。 1. 選擇**儲存變更**。 ## 使用 啟用 API 的承載壓縮 AWS CLI 以下 [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 的非負數整數值 (1 千萬個位元組)。它可衡量壓縮閾值。如果承載大小小於這個值，則不會對承載進行壓縮或解壓縮。因此，請將此值設為零以允許任何承載大小使用壓縮功能。 以下 [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 提出請求時，用戶端可以透過指定 `Accept-Encoding` 標頭與[支援的內容編碼](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)，選擇接收特定格式的壓縮回應承載。 只有符合下列條件時，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 ``` 壓縮回應承載之後，只有壓縮的資料大小會計入數據傳輸費。