API Gateway での REST API のキャッシュ設定

API Gateway で API キャッシュを有効にして、エンドポイントのレスポンスをキャッシュできます。キャッシュを有効にすると、エンドポイントへの呼び出しの数を減らすことができ、また、API へのリクエストのレイテンシーを短くすることもできます。

ステージに対してキャッシュを有効にすると、API Gateway は、秒単位で指定した有効期限 (TTL) が切れるまで、エンドポイントからのレスポンスをキャッシュします。その後、API Gateway は、エンドポイントへのリクエストを行う代わりに、キャッシュからのエンドポイントのレスポンスを調べます。API キャッシュのデフォルトの TTL 値は 300 秒です。最大の TTL 値は 3600 秒です。TTL=0 は、キャッシュが無効なことを意味します。

キャッシュが可能なレスポンスの最大サイズは 1048576 バイトです。キャッシュデータの暗号化は、キャッシュされているときのレスポンスのサイズを増やす可能性があります。

これは HIPAA 対象サービスです。AWS、1996 年制定の医療保険の相互運用性と説明責任に関する法律 (HIPAA)、および AWS のサービスを使用した保護対象医療情報 (PHI) の処理、保存、転送に関する詳細については、HIPAA の概要を参照してください。

Amazon API Gateway のキャッシュを有効にする

API Gateway では、ステージ別にキャッシュを有効にすることができます。

キャッシュを有効にするときは、キャッシュ容量を選択する必要があります。一般的に、容量を大きくすると、パフォーマンスは良くなりますが、コストは増えます。サポートされているキャッシュサイズについては、API Gateway API リファレンスの「cacheClusterSize」を参照してください。

API Gateway で、キャッシュを有効にするには、専用のキャッシュインスタンスを作成します。このプロセスには最長 4 分かかることがあります。

API Gateway で、キャッシュの容量を変更するには、既存のキャッシュインスタンスを削除してから、変更した容量でキャッシュインスタンスを作成します。既存のキャッシュされたデータはすべて削除されます。

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

ステージの [キャッシュ設定] 内でキャッシュを有効にすると、GET メソッドのみがキャッシュされます。API の安全性と可用性を確保するため、この設定を変更しないことをお勧めします。ただし、オーバーライドするメソッドの設定により、他のメソッドのキャッシュを有効にできます。

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

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

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

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

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

メソッドパラメータまたは統合パラメータをキャッシュキーとして使用して、キャッシュされたレスポンスにインデックスを付ける

メソッドパラメータまたは統合パラメータをキャッシュキーとして使用して、キャッシュされたレスポンスにインデックスを付けることができます。これには、カスタムヘッダー、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
...
        

API Gateway コンソールで、キャッシュキーにメソッドリクエストまたは統合リクエストのパラメータを含めるには、パラメータを追加した後に [Caching (キャッシュ)] を選択します。

API Gateway で API ステージキャッシュをフラッシュする

API キャッシュが有効になったら、API ステージのキャッシュをフラッシュして、API のクライアントが統合エンドポイントから最新のレスポンスを取得できるようにします。

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 コンソールで [不正なリクエスト処理] のオプションを選択して、不正なリクエストの処理方法を制御できます。

3 つのオプションにより、次の動作が発生します。