API Gateway 中 REST API 的快取設定 - Amazon API Gateway
啟用 API 快取覆寫方法快取的階段快取使用方法/整合參數作為快取金鑰在 API Gateway 中排清 API 階段快取使 API Gateway 快取項目失效有快取之階段的 AWS CloudFormation 範例

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 概觀。

重要

當您啟用階段的快取時，預設只有 GET 方法會啟用快取。這有助於確保 API 的安全和可用性。您可以透過覆寫方法設定，來啟用其他方法的快取。

重要

快取是按小時計費，基於您選擇的快取大小。快取不符合 AWS 免費方案資格。如需詳細資訊，請參閱 API Gateway 定價。

啟用 Amazon API Gateway 快取

在 API Gateway 中，您可以啟用特定階段的快取。

當您啟用快取，您必須選擇快取容量。一般而言，容量越大效能越佳，但成本也越高。如需支援的快取大小，請參閱 API Gateway API 參考中的 cacheClusterSize。

API Gateway 可透過建立專用快取執行個體來啟用快取。此程序最多需要 4 分鐘的時間。

API Gateway 可透過移除現有的快取執行個體，以及修改容量以建立新的執行個體，來變更快取容量。所有現有的快取資料都會遭到刪除。

注意

快取容量會影響快取執行個體的 CPU、記憶體和網路頻寬。因此，快取容量可能會影響快取的效能。

API Gateway 建議您執行 10 分鐘的負載測試，以確認快取容量適合您的工作負載。確定負載測試期間的流量會反映生產流量。例如，包括提升、持續流量和流量尖峰。負載測試應包含可從快取提供的回應，以及將項目新增至快取的唯一回應。在負載測試期間監控延遲、4xx、5xx、快取命中和快取未命中指標。根據這些指標，視需要調整快取容量。如需有關負載測試的詳細資訊，請參閱如何選取最佳 API Gateway 快取容量，以避免達到速率限制？。

AWS Management Console

在 API Gateway 主控台，您可以在階段頁面上設定快取。您可以佈建階段快取，並指定預設方法層級快取設定。如果您開啟預設方法層級快取，除非該方法具有方法覆寫，否則階段上所有 GET 方法的方法層級快取都會開啟。您部署至階段的其他任何 GET 方法，都會有方法層級快取。若要為階段的特定方法設定方法層級快取設定，您可以使用方法覆寫。如需有關方法覆寫的詳細資訊，請參閱 覆寫方法層級快取的 API Gateway 階段層級快取。

設定指定階段的 API 快取：

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  2. 選擇 Stages (階段)。

  3. 在 API 的 Stages (階段) 清單中，選擇階段。

  4. 在階段詳細資訊區段中，選擇編輯。

  5. 在其他設定下，針對快取設定開啟 API 快取。

    這會為您的階段佈建快取叢集。

  6. 若要為您的階段啟用快取，請開啟預設方法層級快取。

    這會開啟您的階段上所有 GET 方法的方法層級快取。您部署至此階段的其他任何 GET 方法，都會有方法層級快取。

    注意

    如果您有方法層級快取的現有設定，變更預設方法層級快取設定並不會影響現有設定。

    開啟佈建 API 快取和預設方法層級快取。

  7. 選擇儲存變更。

AWS CLI

以下 update-stage 命令會更新階段以佈建快取，並為階段上的所有 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 的安全和可用性，建議您不要變更此設定。但是，您可以透過覆寫方法設定，來啟用其他方法的快取。

如果您想要確認快取是否如預期般運作，您有兩個一般選項：

  • 檢查您 API 與階段的 CloudWatch 指標 CacheHitCount 與 CacheMissCount。

  • 將時間戳記放在回應中。

注意

請勿使用 CloudFront 回應中的 X-Cache 標頭，來判斷您的 API 是否由 API Gateway 快取執行個體所提供。

覆寫方法層級快取的 API Gateway 階段層級快取

您可以開啟或關閉特定方法的快取，藉以覆寫階段層級快取設定。您也可以修改 TTL 期間，或開啟或關閉快取回應的加密功能。

如果您預期正在快取的方法會在其回應中收到敏感資料，請加密快取資料。您可能需要這樣做，才能符合各種合規架構。如需詳細資訊，請參閱《AWS Security Hub 使用者指南》中的 Amazon API Gateway 控制項。

AWS Management Console

如果您在階段詳細資訊中變更預設方法層級快取設定，這並不影響具有覆寫權的方法層級快取設定。

如果您預期正在快取的方法會在其回應中收到敏感性資料，請在 Cache Settings (快取設定) 中，選擇 Encrypt cache data (加密快取資料)。

使用主控台來設定個別方法的 API 快取：

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  2. 選擇 API。

  3. 選擇 Stages (階段)。

  4. 在 API 的 Stages (階段) 清單中，展開階段，然後在 API 中選擇方法。

  5. 在方法覆寫區段中，選擇編輯。

  6. 在方法設定 區段中，開啟或關閉啟用方法快取，或自訂任何其他想要的選項。

    注意

    快取在針對您的階段佈建快取叢集之前，不會起作用。

  7. 選擇儲存。

AWS CLI

以下 update-stage 命令只會關閉 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 Management Console

若要在 API Gateway 主控台中包含方法或整合請求參數作為快取金鑰的一部分，請在新增參數之後選取 Caching (快取)。

包含方法或整合參數做為快取金鑰來編製快取回應的索引
AWS CLI

以下 put-method 命令會建立 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 命令會建立 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 Management Console
若要排清 API 階段快取

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  2. 選擇有快取之階段的 API。

  3. 在主導覽窗格中，選擇階段，然後選擇有快取的階段。

  4. 選擇階段動作功能表，然後選取排清階段快取。

AWS CLI

以下 flush-stage-cache 命令會排清階段快取：

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 值中的其他項目使用萬用字元 (*)。如需如何設定 API Gateway 執行服務許可的詳細資訊，請參閱 使用 IAM 許可權控制 REST API 的存取。

如果您未強制執行 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 Management Console
若要指定處理未經授權請求的方式

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  2. 選擇有快取之階段的 API。

  3. 在主導覽窗格中，選擇階段，然後選擇有快取的階段。

  4. 如需階段詳細資訊，請選擇編輯。

  5. 針對未經授權的請求處理，選取一個選項。

  6. 選擇繼續。

  7. 檢閱變更，然後選擇儲存變更。

AWS CLI

以下 update-stage 命令會更新階段，透過使請求失敗並顯示 403 狀態碼的方式來處理未經授權的請求：

aws apigateway update-stage /
    --rest-api-id a1b2c3 /
    --stage-name 'prod' /
    --patch-operations 'op=replace,path=/*/*/caching/unauthorizedCacheControlHeaderStrategy,value="FAIL_WITH_403"'

有快取之階段的 AWS CloudFormation 範例

下列 AWS CloudFormation 範本會建立範例 API、為 Prod 階段佈建 0.5 GB 快取，以及為所有 GET 方法開啟方法層級快取。

重要

快取是按小時計費，基於您選擇的快取大小。快取不符合 AWS 免費方案資格。如需詳細資訊，請參閱 API Gateway 定價。

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