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、キャッシュヒット、キャッシュミスメトリクスをモニタリングします。これらのメトリクスに基づいて、必要に応じてキャッシュ容量を調整します。負荷テストの詳細については、「レート制限に達しないように、最適な Amazon API Gateway キャッシュ容量を選択するにはどうすればよいですか？」を参照してください。

AWS Management Console

API Gateway コンソールの [ステージ] ページで、キャッシュを設定します。ステージキャッシュをプロビジョニングし、デフォルトのメソッドレベルのキャッシュ設定を指定します。デフォルトのメソッドレベルのキャッシュをオンにすると、メソッドにメソッドオーバーライドがある場合を除き、ステージのすべての GET メソッドでメソッドレベルのキャッシュが有効になります。ステージにデプロイした追加の GET メソッドでは、メソッドレベルのキャッシュが有効になります。ステージの特定のメソッドに対してメソッドレベルのキャッシュ設定を構成するには、メソッドオーバーライドを使用できます。メソッドオーバーライドの詳細については、「API Gateway のステージレベルのキャッシュをメソッドレベルのキャッシュで上書きする」を参照してください。

特定のステージの API キャッシュを設定するには

  1. API Gateway コンソール (https://console.aws.amazon.com/apigateway) にサインインします。

  2. [ステージ] を選択します。

  3. API の [ステージ] リストで、ステージを選択します。

  4. [ステージの詳細] セクションで、[編集] を選択します。

  5. [その他の設定] の [キャッシュ設定] で、[API キャッシュをプロビジョニング] をオンにします。

    これで、ステージのキャッシュクラスターがプロビジョニングされます。

  6. ステージのキャッシュを有効にするには、[デフォルトのメソッドレベルのキャッシュ] をオンにします。

    これにより、ステージのすべての GET メソッドに対してメソッドレベルのキャッシュが有効になります。このステージにデプロイした追加の GET メソッドでは、メソッドレベルのキャッシュが有効になります。

    注記

    メソッドレベルのキャッシュに関する既存の設定がある場合は、デフォルトのメソッドレベルのキャッシュ設定を変更しても、既存の設定には影響しません。

    API キャッシュのプロビジョニングとデフォルトのメソッドレベルのキャッシュをオンにします。

  7. [Save changes] (変更の保存) をクリックします。

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 の安全性と可用性を確保するため、この設定を変更しないことをお勧めします。ただし、オーバーライドするメソッドの設定により、他のメソッドのキャッシュを有効にできます。

キャッシュが想定どおり機能していることを確認するために、2 つの全般的なオプションがあります。

  • API とステージの CacheHitCount および CacheMissCount の CloudWatch メトリクスを調べる。

  • レスポンスにタイムスタンプを入力する。

注記

API が API Gateway キャッシュインスタンスから提供されているかどうかを判断するために、CloudFront レスポンスの X-Cache ヘッダーを使用しないでください。

API Gateway のステージレベルのキャッシュをメソッドレベルのキャッシュで上書きする

特定のメソッドのキャッシュをオンまたはオフにすることで、ステージレベルのキャッシュ設定を上書きできます。TTL 期間を変更したり、キャッシュされたレスポンスの暗号化のオン/オフを切り替えたりすることもできます。

キャッシュするメソッドのレスポンスに機密データが含まれる可能性がある場合は、キャッシュデータを暗号化してください。これは、さまざまなコンプライアンスフレームワークに準拠するために必要になる場合があります。詳細については、AWS Security Hub ユーザーガイドの「Amazon API Gateway のコントロール」を参照してください。

AWS Management Console

[ステージの詳細] でデフォルトのメソッドレベルのキャッシュ設定を変更しても、オーバーライドが設定されたメソッドレベルのキャッシュ設定には影響しません。

キャッシュ中のメソッドがそのレスポンスで機密データを受け取ることが予想される場合は、[キャッシュ設定] で [キャッシュデータを暗号化する] を選択します。

コンソールを使用してメソッド別の API キャッシュを設定するには

  1. API Gateway コンソール (https://console.aws.amazon.com/apigateway) にサインインします。

  2. [API] を選択します。

  3. [ステージ] を選択します。

  4. API の [ステージ] リストで、ステージを展開し、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 パス、またはクエリ文字列が含まれます。これらのパラメータの一部またはすべてをキャッシュキーとして指定できますが、少なくとも 1 つの値を指定する必要があります。キャッシュキーがある場合、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 コマンドは、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 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 実行ロールにアタッチします。

注記

クロスアカウントのキャッシュ無効化はサポートされていません。


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:InvalidateCache"
      ],
      "Resource": [
        "arn:aws:execute-api:region:account-id:api-id/stage-name/GET/resource-path-specifier"
      ]
    }
  ]
}

このポリシーでは、API Gateway 実行サービスが指定された 1 つまたは複数のリソースのリクエストに対してキャッシュを無効にします。対象リソースのグループを指定するには、account-id、api-id、および他のエントリの ARN 値 Resource に対してワイルドカード文字 (*) を使用します。API Gateway 実行サービスのアクセス許可の設定方法については、「IAM アクセス許可を使用して REST API へのアクセスを制御する」を参照してください。

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 Management Console
未認可リクエストの処理方法を指定するには

  1. API Gateway コンソール (https://console.aws.amazon.com/apigateway) にサインインします。

  2. キャッシュを含むステージがある API を選択します。

  3. メインナビゲーションペインで、[ステージ] を選択し、キャッシュを含むステージを選択します。

  4. [ステージの詳細] で、[編集] を選択します。

  5. [未認可リクエストの処理] でオプションを選択します。

  6. [Continue] (続行) をクリックします。

  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 の例

次の 0.5 テンプレートは、API の例を作成し、Prod ステージに AWS CloudFormation 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