パフォーマンス向上のためのレスポンスのキャッシュ
レスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーを使用して、API Gatewayでバックエンド・サービスに送信されるリクエストの数を減らす方法をご紹介します。
通常、バックエンド・サービスに不要な負荷をかけることを避けて、パフォーマンスを向上させ、コストを削減します。この負荷を軽減する1つの方法は、後でレスポンスを再利用できる場合に備えてリクエストへのレスポンスをキャッシュすることです。同様のリクエストを受信した場合は、リクエストをバックエンド・サービスに送信するのではなく、レスポンス・キャッシュからデータを取得することで満たすことができます。
APIゲートウェイ・サービスは、RedisやKeyDBサーバーなど、すでにアクセス可能な外部キャッシュ・サーバーと統合できます。APIゲートウェイ・サービスによって管理されるAPIゲートウェイは、次のように構成できます:
- 元のリクエストに応答してバックエンド・サービスによって返されたデータをキャッシュ・サーバーに格納します。
- バックエンド・サービスに後のリクエストを送信せずに、元のリクエストと同様の後のリクエストに応答して、以前に格納されたデータをキャッシュ・サーバーから取得します。
レスポンス・キャッシュ用のAPIゲートウェイを構成するには:
- APIゲートウェイでのレスポンス・キャッシュの有効化(APIゲートウェイでのレスポンス・キャッシュの有効化を参照)
- リクエスト・ポリシーおよびレスポンス・ポリシーを使用して、APIゲートウェイ内の個々のルートのレスポンス・キャッシュを設定します(「レスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーの追加」を参照)。
レスポンス・キャッシュは、次の方法で設定できます。
- コンソールの使用
- JSONファイルの編集
レスポンス・キャッシュの機能
APIゲートウェイでレスポンス・キャッシュを有効にした場合、APIゲートウェイはAPIクライアントからのリクエストを分析し、レスポンス・キャッシュ・ポリシーを持つルートにします。APIゲートウェイは、レスポンスがすでにキャッシュ・サーバーに格納されている以前の類似リクエストと新しいリクエストを照合しようとします。レスポンスのHTTPステータス・コードが200、204、301または410の場合、APIゲートウェイはGET、HEADおよびOPTIONSリクエストのレスポンスをキャッシュ・サーバーに格納します。APIゲートウェイは、設定したレスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーを使用し、リクエストまたはレスポンスのキャッシュ制御ヘッダー(存在する場合)は無視します。
キャッシュ・サーバー内のレスポンスを一意に識別するために、APIゲートウェイは、レスポンスを明示したGET、HEADおよびOPTIONSリクエストから導出されたキャッシュ・キーを使用します。デフォルトでは、キャッシュ・キーは次のもので構成されます。
- レスポンスを明示したリクエストのURL (URL内の問合せパラメータを除く)
- HTTPメソッド(GET、HEADまたはOPTIONSのいずれか)
- リクエストを受信したAPIデプロイメントのOCID
キャッシュされたレスポンスを特定のリクエストとより密接に一致させるために、リクエストからキャッシュ・キーに1つ以上のコンテキスト変数の値を追加することで、オプションでキャッシュ・キーをカスタマイズできます(キャッシュ・キーのカスタマイズに関するノートを参照)。
次に何が行われるかは、APIゲートウェイが新しいGET、HEADまたはOPTIONSリクエストを以前の同様のリクエストからのレスポンスと照合できるかどうかによって異なります。
- APIゲートウェイがキャッシュ・サーバーで一致するキャッシュ・キーを検出した場合、APIゲートウェイは対応するレスポンス・データをキャッシュ・サーバーから取得し、レスポンスとしてAPIクライアントに送信します。
- APIゲートウェイがキャッシュ・サーバーに一致するキャッシュ・キーを検出しない場合、APIゲートウェイはリクエストをバックエンド・サービスに転送します。バックエンド・サービスがレスポンスを返すと、APIゲートウェイはレスポンスをAPIクライアントに送信し、レスポンスを新しいキャッシュ・キーとともにキャッシュ・サーバーに格納します。
X-Cache-Status
は、次のようにレスポンスがキャッシュ・サーバーから取得されたかどうかを示します。X-Cache-Status: HIT
は、キャッシュ・サーバーに一致するキャッシュ・キーが見つかったため、レスポンスがキャッシュ・サーバーから取得されたことを示します。X-Cache-Status: MISS
は、キャッシュ・サーバーに一致するキャッシュ・キーが見つからなかったため、レスポンスはバックエンド・サービスから取得されたことを示します。X-Cache-Status: BYPASS
は、キャッシュ・サーバーがチェックされなかったため、レスポンスがバックエンド・サービスから取得されたことを示します。キャッシュ・サーバーをチェックしない理由には、キャッシュ・サーバーとの通信の問題、および特定のリクエストのレスポンスがキャッシュ・サーバーから取得されないようにする構成設定があります。
ヒント:レスポンスに追加のX-Cache-Status
ヘッダーが含まれないようにするには、ヘッダー変換レスポンス・ポリシーを使用して削除します(ヘッダー変換レスポンス・ポリシーの追加を参照)。
レスポンス・キャッシングとセキュリティに関するノート
キャッシュ・サーバー上のデータがセキュアに格納およびアクセスされるようにするには:
- APIゲートウェイを設定して、Vaultサービスのボールトにシークレットとして保存された資格証明を使用してキャッシュ・サーバーで認証します。
- APIゲートウェイとTLS対応キャッシュ・サーバーの間にTLS (以前のSSL)を介してセキュアな接続を設定するかどうか、およびTLS証明書を検証するかどうかを指定できます。現在検証されているのは、パブリック認証局によって署名された証明書のみです。
- 失効時間を指定して、キャッシュされたデータが長期間保存されないこと、および失効したデータがキャッシュ・サーバーから返されないようにすることができます。
- キャッシュ・キーに一致するリクエストURLを制限するには、リクエストURLに存在する1つ以上のパラメータを含めるようにキャッシュ・キーをカスタマイズします(キャッシュ・キーのカスタマイズに関するノートを参照)。
- 資格証明を含むリクエストのレスポンスをキャッシュしないように指定できます(資格証明を含むリクエストのレスポンスのキャッシュに関するノート(プライベート・キャッシュ)を参照)。
キャッシュ・サーバー自体が、格納されているデータを保護するために正しく構成されていることを確認するのはユーザーの責任です。具体的には、Oracleでは、既存のキャッシュ・サーバーを再利用しないことを強くお薦めします。かわりに、Oracleでは、APIゲートウェイ・レスポンス・キャッシュ専用の新しいキャッシュ・サーバーを設定し、キャッシュ・サーバーへのアクセスをAPIゲートウェイのみに制限することをお薦めします。
資格証明を含むリクエストのレスポンスのキャッシュに関するノート(プライベート・キャッシュ)
リクエストには、バックエンド・サービスでAPIクライアントを認証するための資格証明を含む認可ヘッダーを含めることができます。資格証明は通常、個人または組織に対してプライベートなデータへのアクセスを提供します。たとえば、認証トークンを含むリクエスト認可ヘッダーを使用して、銀行口座情報を含むレスポンスを明示できます。リクエストに認可ヘッダーが存在することは、レスポンスが機密性があり、それを表示できるものと共有される可能性があることを示しています。
同様に、認証および認可に認可プロバイダ・ファンクションを使用した場合、認証ポリシーは、アクセス・トークンを含むリクエスト内のヘッダーまたは問合せパラメータを識別します(認証および認可をAPIデプロイメントに追加するための認可プロバイダ・ファンクションへのトークンの受渡しを参照)。認証ポリシーで識別されるヘッダーまたは問合せパラメータのリクエスト内に存在することも、レスポンスが機密性があり、それを表示できるものと共有される可能性があることを示しています。
認可ヘッダーを含むリクエスト、または認証ポリシーで識別されたヘッダーまたは問合せパラメータを含むリクエストに対するレスポンスのキャッシュは、プライベート・キャッシュと呼ばれます。プライベート・キャッシングは、将来同様のリクエストへのレスポンスを高速化できますが、データ・セキュリティを損なう可能性があります。そのため、セキュリティ違反を回避するために、プライベート・キャッシュはデフォルトで無効になっています。ただし、ルート・バイ・ルート・ベースでは、プライベート・キャッシュを有効にできます。
プライベート・キャッシュを有効にする場合は、キャッシュ・キーをカスタマイズしてレスポンスを分離することをお薦めします。これにより、各レスポンスは、表示を許可されたレスポンスにのみ返されます。例:
- リクエスト認可ヘッダーの値、または認証ポリシーで識別されるヘッダーまたは問合せパラメータの値を、コンテキスト表のコンテキスト変数としてキャッシュ・キーに追加します。
- 認証および認可に認可プロバイダ・ファンクションまたはJWTを使用した場合は、リクエスト・プリンシパル(
sub
やprincipalId
など)を識別するコンテキスト変数の値を、request.auth
コンテキスト表のキャッシュ・キーに追加します。APIデプロイメントへの認証と認可の追加を参照してください。
コンテキスト変数のキャッシュ・キーに値を持つキャッシュされたレスポンスは、一致する値を持つリクエストへのレスポンスとしてのみ返されます。
キャッシュされたレスポンスを十分に分離するキャッシュ・キーの追加は、ユーザーの責任で行ってください。「キャッシュ・キーのカスタマイズに関するノート」を参照してください。
キャッシュ・キーのカスタマイズに関するノート
キャッシュ・サーバーに格納されているレスポンスは、キャッシュ・キーによって一意に識別されます。デフォルトでは、キャッシュ・キーは、レスポンスを明示したリクエストのURL (リクエストに存在するコンテキスト変数を除く)、HTTPメソッドおよびAPIデプロイメントのOCIDから導出されます。キャッシュされたレスポンスを特定のリクエストとより緊密に一致させるために、リクエストからキャッシュ・キーに1つ以上のコンテキスト変数の値を追加して、オプションでキャッシュ・キーをカスタマイズできます。認可ヘッダーを含むリクエスト、または認証ポリシーで識別されるヘッダーまたは問合せパラメータを含むリクエストに対してプライベート・キャッシュを有効にする場合は、それらの値をコンテキスト変数としてキャッシュ・キーに追加することをお薦めします。
キャッシュ・キーに追加するコンテキスト変数値を指定するには、<context-table-name>.[<key>]
という形式を使用します。ここでは:
<context-table-name>
は、request.query
、request.headers
またはrequest.auth
のいずれかです<key>
は次のいずれかです:- APIへのリクエストに含まれる問合せパラメータ名
- APIへのリクエストに含まれるヘッダー名
- 認可プロバイダ・ファンクションによって返される、またはJWTトークンに含まれる認証パラメータ名
- APIへのリクエストの
Host
ヘッダー・フィールド
例:
- リクエスト・ヘッダーに含まれているときに
X-Username
コンテキスト変数の値をキャッシュ・キーに追加するには、キャッシュ・キーの追加としてrequest.headers[X-Username]
を指定します。 - リクエスト・プリンシパル(リクエストを送信するユーザーまたはアプリケーション)がJWTトークンに
sub
クレームとして含まれているときにキャッシュ・キーに追加するには、キャッシュ・キーの追加としてrequest.auth[sub]
を指定します。 Authorization
ヘッダーの値をキャッシュ・キーに追加するには、キャッシュ・キーの追加としてrequest.headers[Authorization]
を指定します。- 認可プロバイダ・ファンクションによって返され、
X-Custom-Auth
という名前のヘッダーに含まれるアクセス・トークンの値をキャッシュ・キーに追加するには、キャッシュ・キーの追加としてrequest.headers[X-Custom-Auth]
を指定します。 - リクエストに含まれる
Host
ヘッダー・フィールドの値をキャッシュ・キーに追加するには、request.host
を指定します。
コンテキスト変数の詳細は、ポリシーおよびHTTPバック・エンド定義へのコンテキスト変数の追加を参照してください。
レスポンス・キャッシュの前提条件
APIゲートウェイのレスポンス・キャッシュを有効にする前に:
- RESPプロトコルを実装するキャッシュ・サーバー(RedisやKeyDBなど)がすでに設定されており、使用可能である必要があります。
- APIゲートウェイのサブネットがキャッシュ・サーバーにアクセスできる必要があります。
- キャッシュ・サーバーは、単一のキャッシュ・サーバー・ホストでホストする必要があり、クラスタ内の複数のインスタンスに分散されません。
- キャッシュ・サーバーをシークレットとしてVaultサービス内のボールトに認証するには、資格証明をすでに格納しておく必要があり(Vaultでのシークレットの作成を参照)、シークレットのOCIDおよびバージョン番号を知っている必要があります。シークレットの内容を指定する場合は、
{"username":"<cache-server-username>", "password":"<cache-server-password>"}
という形式を使用します。ユーザー名の指定はオプションです。例:{"password":"<cache-server-password>"}
- キャッシュ・サーバーで認証するための資格証明を含むVaultサービスのシークレットにアクセスするには、動的グループ内のAPIゲートウェイに権限を付与するポリシーをすでに設定しておく必要があります(Vaultサービスのシークレットとして格納された資格証明にAPIゲートウェイへのアクセス権を付与するポリシーの作成を参照)。
APIゲートウェイでのレスポンス・キャッシュの有効化
APIゲートウェイでレスポンス・キャッシュを有効にするには、コンソールを使用するか、JSONファイルを編集します。
コンソールを使用したレスポンス・キャッシングの有効化および構成
コンソールを使用してAPIゲートウェイのレスポンス・キャッシュを有効化および構成するには:
-
コンソールを使用してAPIゲートウェイを作成または更新します。
詳細は、APIゲートウェイの作成およびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
-
「ゲートウェイの作成」ダイアログの「拡張オプション」セクションで、「レスポンス・キャッシュ」の横にある「有効化」ボタンをクリックし、次のようにします。
- 「キャッシュ・サーバー」オプションを次のように指定します。
-
Host:キャッシュ・サーバーのホスト名。たとえば、
"cache.example.com"
です。 -
ポート番号:キャッシュ・サーバーのポート番号。たとえば、
6379
です。
-
Host:キャッシュ・サーバーのホスト名。たとえば、
- 「キャッシュ・サーバー資格証明」オプションを次のように指定します。
- Vault: Vaultサービス内のボールトの名前。キャッシュ・サーバーにログインするための資格証明が含まれます。
- Vaultシークレット:キャッシュ・サーバーにログインするための資格証明を含む、指定されたボールト内のシークレットの名前。
- Vaultシークレット・バージョン番号:使用するシークレットのバージョン。
- 「キャッシュ・サーバー接続」オプションを次のように指定します。
- リクエストでのSSL/TLSの使用:キャッシュ・サーバーがTLS対応であるかどうか、したがって、APIゲートウェイとTLS (以前のSSL)を介したキャッシュ・サーバーとの間にセキュアな接続を設定するかどうか。
- SSL/TLS証明書の検証: APIゲートウェイがキャッシュ・サーバーのTLS (以前のSSL)証明書を検証するかどうか。現在検証されているのは、パブリック認証局によって署名された証明書のみです。
- 接続タイムアウト:キャッシュ・サーバーへの接続試行を中止するまでの待機時間(ミリ秒)。APIゲートウェイがこの時間内にキャッシュ・サーバーに接続できない場合、APIゲートウェイはキャッシュ・サーバーから以前にキャッシュされたデータを取得せず、将来再利用される可能性があるため、新しいデータをキャッシュ・サーバーに書き込みません。
- 読取りタイムアウト:キャッシュ・サーバーからのデータの読取り試行を中止するまでの待機時間(ミリ秒)。この時間内にAPIゲートウェイがキャッシュ・サーバーからデータを取得できない場合、APIゲートウェイはかわりにバックエンド・サービスにリクエストを送信します。
- 送信タイムアウト:キャッシュ・サーバーへのデータの書込み試行を中止するまでの待機時間(ミリ秒)。この時間内にAPIゲートウェイがキャッシュ・サーバーにデータを送信できない場合、将来再利用される可能性があるため、レスポンスはキャッシュされません。
- 「キャッシュ・サーバー」オプションを次のように指定します。
- 「作成」または「変更の保存」をクリックして、APIゲートウェイを作成または更新します。
CLIおよびJSONファイルを使用したレスポンス・キャッシングの有効化および構成
CLIおよびJSONファイルを使用してAPIゲートウェイのレスポンス・キャッシュを有効化および構成するには:
-
任意のJSONエディタを使用して、次の形式でキャッシュ構成ファイルを作成します:
{ "type" : "EXTERNAL_RESP_CACHE", "servers" : [ { "host" : "<cache-server-hostname>", "port" : <port-number> } ], "authenticationSecretId" : "<secret-ocid>", "authenticationSecretVersionNumber" : <secret-version-number>, "isSSLEnabled" : <true|false>, "isSSLVerifyDisabled" : <true|false>, "connectTimeoutInMs" : <milliseconds>, "readTimeoutInMs" : <milliseconds>, "readTimeoutInMs" : <milliseconds> }
ここでは:"type" : "EXTERNAL_RESP_CACHE"
は、レスポンス・キャッシュを有効にすることを示します。設定しない場合、デフォルトは"type" : "NONE"
で、レスポンス・キャッシュが無効であることを示します。"host" : "<cache-server-hostname>"
は、キャッシュ・サーバーのホスト名です。たとえば、"host" : "cache.example.com"
。"port" : <port-number>
は、キャッシュ・サーバーのポート番号です。たとえば、"port" : 6379
です。"authenticationSecretId" : "<secret-ocid>"
は、Vaultサービスのボールトに定義されているシークレットのOCIDで、キャッシュ・サーバーにログインするための資格証明が含まれます。たとえば、"authenticationSecretId" : "ocid.oc1.sms.secret.aaaaaa______gbdn"
です。"authenticationSecretVersionNumber" : <secret-version-number>
は、使用するシークレットのバージョンです。例、"authenticationSecretVersionNumber" : 1
"isSSLEnabled" : <true|false>
は、キャッシュ・サーバーがTLS対応であるかどうか、およびTLS (以前のSSL)を介したAPIゲートウェイとキャッシュ・サーバー間のセキュアな接続を設定するかどうかを示します。設定しない場合、デフォルトはfalse
です"isSSLVerifyDisabled" : <true|false>
は、APIゲートウェイがキャッシュ・サーバーのTLS (以前のSSL)証明書を検証するかどうかを示します。現在検証されているのは、パブリック認証局によって署名された証明書のみです。設定しない場合、デフォルトはfalse
です"connectTimeoutInMs" : <milliseconds>
は、キャッシュ・サーバーへの接続を中止するまでの待機時間(ミリ秒)を示します。APIゲートウェイがこの時間内にキャッシュ・サーバーに接続できない場合、APIゲートウェイはキャッシュ・サーバーから以前にキャッシュされたデータを取得せず、将来再利用される可能性があるため、新しいデータをキャッシュ・サーバーに書き込みません。設定しない場合、デフォルトは1000
です。例、"connectTimeoutInMs" : 1500
"readTimeoutInMs" : <milliseconds>
は、キャッシュ・サーバーからのデータの読取りを中止するまでの待機時間(ミリ秒)を示します。APIゲートウェイがこの時間内にキャッシュ・サーバーからデータを取得できない場合、APIゲートウェイはかわりにバックエンド・サービスにリクエストを送信します。設定しない場合、デフォルトは1000
です。例、"readTimeoutInMs" : 250
"sendTimeoutInMs" : <milliseconds>
は、キャッシュ・サーバーへのデータの書込みを中止するまでの待機時間(ミリ秒)を示します。APIゲートウェイがこの時間内にキャッシュ・サーバーにデータを送信できない場合、レスポンスは今後再利用できるようにキャッシュされません。設定しない場合、デフォルトは1000
です。例、"sendTimeoutInMs" : 1250
例:
{ "type" : "EXTERNAL_RESP_CACHE", "servers" : [ { "host" : "cache.example.com", "port" : 6379 } ], "authenticationSecretId" : "ocid.oc1.sms.secret.aaaaaa______gbdn", "authenticationSecretVersionNumber" : 1, "isSSLEnabled" : true, "isSSLVerifyDisabled" : false, "connectTimeoutInMs" : 1000, "readTimeoutInMs" : 250, "sendTimeoutInMs" : 1000 }
- 選択した名前でキャッシュ構成ファイルを保存します。例:
resp-cache-config.json
- CLIを使用してAPIゲートウェイを作成または更新する場合は、キャッシュ構成ファイルを使用します:
- レスポンス・キャッシュを有効にして新しいAPIゲートウェイを作成するには、APIゲートウェイの作成のCLIの手順に従って、
--response-cache-details
パラメータをキャッシュ構成ファイルの名前と場所に設定します。例:oci api-gateway gateway create --display-name "Hello World Gateway" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --endpoint-type "PRIVATE" --subnet-id ocid1.subnet.oc1.iad.aaaaaaaaz______rca --response-cache-details file:///etc/caches/resp-cache-config.json
- 既存のAPIゲートウェイを更新してレスポンス・キャッシュを有効にするか、レスポンス・キャッシュ設定を変更するには、APIゲートウェイまたはAPIデプロイメントの更新のCLIの手順に従って、
--response-cache-details
パラメータをキャッシュ構成ファイルの名前と場所に設定します。例:oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --response-cache-details file:///etc/caches/resp-cache-config.json
- レスポンス・キャッシュを有効にして新しいAPIゲートウェイを作成するには、APIゲートウェイの作成のCLIの手順に従って、
レスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーの追加
レスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーをAPIデプロイメント仕様に追加するには、コンソールを使用するか、JSONファイルを編集します。リクエストおよびレスポンス・ポリシーを有効にするには、APIゲートウェイでレスポンス・キャッシュを有効にする必要があります。
コンソールを使用したレスポンス・キャッシュのリクエストおよびレスポンス・ポリシーの追加
コンソールを使用してレスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーをAPIデプロイメント仕様に追加するには:
-
コンソールを使用してAPIデプロイメントを作成または更新し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
-
「次」をクリックして、「ルート」ページのAPIデプロイメント内の個々のルートの詳細を入力し、「レスポンス・キャッシュ」をクリックします。
- 「このルートのキャッシュ」オプションを選択し、この特定のルートに適用されるレスポンス・キャッシュ・オプションを指定します:
- キャッシュされたレスポンスのTTL (Time To Live) (秒):キャッシュされたデータが、この特定のルートのキャッシュ・サーバーで使用可能な時間。
- キャッシュ・キーの追加:キャッシュされたレスポンスを特定のリクエストとより密接に関連付けるために、デフォルトのキャッシュ・キーに追加する1つ以上のコンテキスト変数。たとえば、
request.headers[X-Username]
です。一般的に使用されるコンテキスト変数のリストから選択することも、任意のコンテキスト変数を入力することもできます。コンテキスト変数の前に$記号を付けたり、中カッコで囲んだりしないでください(JSONファイルのAPIデプロイメント仕様のURLにコンテキスト変数を追加する場合のように)。詳細は、「キャッシュ・キーのカスタマイズに関するノート」を参照してください。
- 認可ヘッダーを含むリクエスト、または認証ポリシーで識別されるヘッダーまたは問合せパラメータを含むリクエストのレスポンスをキャッシュする場合は、「認可ヘッダーを使用してレスポンスをキャッシュ」オプションを選択します。
このようなリクエストに対するレスポンスをキャッシュすると、データ・セキュリティが損なわれる場合があります。詳細は、資格証明を含むリクエスト(プライベート・キャッシュ)のレスポンスのキャッシュに関するノートを参照してください。
- 「次」をクリックして、APIデプロイメント用に入力した詳細を確認します。
- APIデプロイメントを作成または更新するには、「作成」または「変更の保存」をクリックします。
- (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。
レスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーを追加するためのJSONファイルの編集
レスポンス・キャッシュを特定のルートに追加するには、リクエスト・ポリシーとレスポンス・ポリシーの両方を追加する必要があります。
JSONファイル内のAPIデプロイメント仕様にレスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーを追加するには:
-
任意のJSONエディタを使用して、レスポンス・キャッシュを追加する既存のAPIデプロイメント仕様を編集するか、新しいAPIデプロイメント仕様を作成します(APIデプロイメント仕様の作成を参照)。
たとえば、次の基本的なAPIデプロイメント仕様では、OCI Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
個々のルートに適用されるレスポンス・キャッシュ・リクエストおよびレスポンス・ポリシーを指定するには:
-
requestPolicies
セクションとresponsePolicies
セクションの両方を、ポリシーを適用するルートのバックエンド・セクションの後に挿入します。例:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": {}, "responsePolicies": {} } ] }
- 次の
responseCacheLookup
リクエスト・ポリシーを新しいrequestPolicies
セクションに追加して、ルートに適用します:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "responseCacheLookup": { "type": "SIMPLE_LOOKUP_POLICY", "isEnabled": true, "isPrivateCachingEnabled": <true|false>, "cacheKeyAdditions": [<list-of-context-variables>] } }, "responsePolicies": {} } ] }
ここでは:
"type": "SIMPLE_LOOKUP_POLICY"
は、実装するレスポンス・キャッシュのタイプです。"SIMPLE_LOOKUP_POLICY"
のみが現在サポートされています。"isEnabled": true
は、レスポンス・キャッシングがルートに対して有効であることを示します。レスポンス・キャッシュを一時的に無効にする場合は、"isEnabled": false
を設定します。指定しない場合、デフォルトはtrue
です。"isPrivateCachingEnabled": <true|false>
は、認可ヘッダーを含むリクエスト、または認証ポリシーで識別されるヘッダーまたは問合せパラメータを含むリクエストのレスポンスをキャッシュするかどうかを示します。このようなリクエストに対するレスポンスをキャッシュすると、データ・セキュリティが損なわれる場合があります。指定しない場合、デフォルトはfalse
で、このようなリクエストのレスポンスがキャッシュされないことを示します。詳細は、資格証明を含むリクエスト(プライベート・キャッシュ)のレスポンスのキャッシュに関するノートを参照してください。"cacheKeyAdditions": [<list-of-context-variables>]
は、デフォルトのキャッシュ・キーに追加するコンテキスト変数のオプションのカンマ区切りリストであり、キャッシュされたレスポンスを特定のリクエストとより密接に関連付けます。たとえば、"cacheKeyAdditions": ["request.headers[Accept]"]
です。コンテキスト変数の前に$記号を付けたり、中カッコで囲んだりしないでください(JSONファイルのAPIデプロイメント仕様のURLにコンテキスト変数を追加する場合と同様に)。詳細は、「キャッシュ・キーのカスタマイズに関するノート」を参照してください。
- 次の
responseCacheStorage
レスポンス・ポリシーを新しいresponsePolicies
セクションに追加して、ルートに適用します:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "responseCacheLookup": { "type": "SIMPLE_LOOKUP_POLICY", "isEnabled": true, "isPrivateCachingEnabled": false, "cacheKeyAdditions": ["request.headers[Accept]"] } }, "responsePolicies": { "responseCacheStorage": { "type": "FIXED_TTL_STORE_POLICY", "timeToLiveInSeconds": <seconds> } } } ] }
ここでは:
"type": "FIXED_TTL_STORE_POLICY"
は、レスポンスを格納するレスポンス・キャッシュのタイプです。"FIXED_TTL_STORE_POLICY"
のみが現在サポートされています。"timeToLiveInSeconds": <seconds>
は、この特定のルートについてキャッシュ・サーバーでキャッシュされたデータを使用できる期間を指定します。例、"timeToLiveInSeconds": 300
例:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "responseCacheLookup": { "type": "SIMPLE_LOOKUP_POLICY", "isEnabled": true, "isPrivateCachingEnabled": false, "cacheKeyAdditions": ["request.headers[Accept]"] } }, "responsePolicies": { "responseCacheStorage": { "type":"FIXED_TTL_STORE_POLICY", "timeToLiveInSeconds": 300 } } } ] }
-
- APIデプロイメント仕様を含むJSONファイルを保存します。
-
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- 「既存のAPIのアップロード」オプションを選択して、コンソールでJSONファイルを指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
- (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。