APIデプロイメント仕様へのリクエスト・ポリシーとレスポンス・ポリシーの追加
APIゲートウェイで以前に作成したAPI仕様にリクエスト・ポリシーおよびレスポンス・ポリシーを追加することによってAPIデプロイメントの動作を制御する方法を確認します。
APIデプロイメント仕様にリクエスト・ポリシーおよびレスポンス・ポリシーを追加すると、APIゲートウェイで作成するAPIデプロイメントの動作を制御できます:
- リクエスト・ポリシーでは、APIクライアントから受信したリクエストをバックエンドに送信する前に実行するアクションを記述します
- レスポンス・ポリシーでは、バックエンドから返されたレスポンスをAPIクライアントに送信する前に実行するアクションを記述します
リクエスト・ポリシーまたはレスポンス・ポリシー(あるいはその両方)は、次の目的で使用できます:
- バックエンド・サービスに送信するリクエスト数を制限します
- CORS (Cross-Origin Resource Sharing)サポートを有効にします
- 認証および認可を提供します
- mTLSサポートの追加
- リクエストをバックエンド・サービスに送信する前に検証します
- 受信リクエストおよび送信レスポンスを変更します
- レスポンスをキャッシュしてパフォーマンスを向上させ、バックエンド・サービスの負荷を軽減
- サブスクライバ・アクセスを監視および管理する使用プランにAPIデプロイメントを含めることを許可する
APIデプロイメント仕様のすべてのルートにグローバルに適用されるポリシーをAPIデプロイメント仕様に追加できます。また、特定のルートのみに適用されるポリシーを追加することもできます。
APIゲートウェイのリクエスト・ポリシーとレスポンス・ポリシーは、Oracle Cloud Infrastructureリソースへのアクセスを制御するIAMポリシーとは異なることに注意してください。
次を実行して、リクエスト・ポリシーおよびレスポンス・ポリシーをAPIデプロイメント仕様に追加できます:
- コンソールの使用
- JSONファイルの編集
コンソールを使用したリクエスト・ポリシーおよびレスポンス・ポリシーの追加
コンソールを使用してリクエスト・ポリシーおよびレスポンス・ポリシーをAPIデプロイメント仕様に追加するには:
-
コンソールを使用してAPIデプロイメントを作成し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイの更新を参照してください。
-
「基本情報」ページの「APIリクエスト・ポリシー」セクションで、APIデプロイメント仕様のすべてのルートにグローバルに適用するリクエスト・ポリシーを指定します:
- 相互TLS:リクエストを行うAPIクライアントによって提示されたTLS証明書に基づいて、APIゲートウェイにデプロイするAPIへのアクセスを制御するポリシー。mTLSポリシーは、APIデプロイメント仕様のすべてのルートにのみグローバルに適用できます(個々のルートには適用できません)。「APIデプロイメントへのmTLSサポートの追加」を参照してください。
- CORS: APIゲートウェイにデプロイするAPIでCORSサポートを有効化するポリシー。APIデプロイメント仕様の個々のルートに適用するCORSポリシーも指定できます(最初にグローバルCORSポリシーを入力する必要はありません)。CORSサポートをAPIデプロイメントに追加を参照してください。
- レート制限: APIクライアントがバックエンド・サービスにリクエストを行うことのできるレートを制限するポリシー。APIデプロイメント仕様の(個々のルートではなく)すべてのルートにのみグローバルにレート制限ポリシーを適用できます。APIゲートウェイ・バック・エンドへのリクエストの数の制限を参照してください。
-
「次」を選択して、「認証」ページでグローバル認証リクエスト・ポリシーを定義するオプションを指定します。
認証リクエスト・ポリシーは、APIゲートウェイにデプロイするAPIへのアクセスを制御します。最初にグローバル認証ポリシーを指定すると、APIデプロイメント仕様の個々のルートに適用する認可ポリシーを指定できます。APIデプロイメントへの認証と認可の追加を参照してください。
-
「次」を選択して、「ルート」ページのAPIデプロイメント内の個々のルートの詳細を入力します。
-
個々のルートに適用するリクエスト・ポリシーを指定するには、「リクエスト・ポリシーのルーティングを表示」を表示を選択して、次を指定します:
- 認可: エンド・ユーザーのアクセス・スコープに基づいて、エンド・ユーザーが実行できる操作を指定するポリシー。個々のルートに対して認可ポリシーを指定する前に、グローバル認証ポリシーをすでに指定している必要があります。APIデプロイメントへの認証と認可の追加を参照してください。
- CORS: APIデプロイメント仕様の個々のルートに対してCORSサポートを有効化するポリシー(最初にグローバルCORSポリシーを入力する必要はありません)。CORSサポートをAPIデプロイメントに追加を参照してください。
- ヘッダー検証:リクエストのヘッダーを検証するポリシー。コンソールを使用した検証リクエスト・ポリシーの追加を参照してください。
- 問合せパラメータの検証:リクエストの問合せパラメータを検証するポリシー。コンソールを使用した検証リクエスト・ポリシーの追加を参照してください。
- 本文検証:リクエストの本文のコンテンツを検証するポリシー。コンソールを使用した検証リクエスト・ポリシーの追加を参照してください
- ヘッダー変換: リクエストのヘッダーを追加、削除および変更するポリシー。コンソールを使用したヘッダー変換リクエスト・ポリシーの追加を参照してください。
- 問合せ変換: リクエストの問合せパラメータを追加、削除および変更するポリシー。コンソールを使用した問合せパラメータ変換リクエスト・ポリシーの追加を参照してください。
-
個々のルートに適用するレスポンス・ポリシーを指定するには、「ルート・レスポンス・ポリシーの表示」を選択して、次を指定します:
- ヘッダー変換: レスポンスのヘッダーを追加、削除および変更するポリシー。コンソールを使用したヘッダー変換レスポンス・ポリシーの追加を参照してください。
- 「次」を選択して、APIデプロイメント用に入力した詳細を確認します。
- APIデプロイメントを作成または更新するには、「作成」または「変更の保存」を選択します。
- (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。
リクエスト・ポリシーおよびレスポンス・ポリシーを追加するためのJSONファイルの編集
JSONファイルのAPIデプロイメント仕様にリクエスト・ポリシーおよびレスポンス・ポリシーを追加するには:
-
任意のJSONエディタを使用して、リクエスト・ポリシーまたはレスポンス・ポリシーを追加する既存のAPIデプロイメント仕様を編集するか、新しいAPIデプロイメント仕様を作成します(APIデプロイメント仕様の作成を参照)。
APIデプロイメント仕様には、少なくとも次の内容を含む
routes
セクションが含まれます:- パス。たとえば、
/hello
です - 1つ以上のメソッド。たとえば、
GET
です - バック・エンドの定義。たとえば、URLまたはOCIファンクション内のファンクションのOCIDです。
たとえば、次の基本的なAPIデプロイメント仕様では、OCI Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
- パス。たとえば、
-
APIデプロイメント仕様内のすべてのルートにグローバルに適用するリクエスト・ポリシーを追加するには:
-
routes
セクションの前にrequestPolicies
セクションを挿入します。例:{ "requestPolicies": {}, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
requestPolicies
セクションにリクエスト・ポリシーを含めます。たとえば、APIデプロイメント仕様のすべてのルートに送信するリクエストの数を制限するには、
requestPolicies
セクションにrateLimiting
ポリシーを次のように含めます:{ "requestPolicies": { "rateLimiting": { "rateKey": "CLIENT_IP", "rateInRequestsPerSecond": 10 } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
rateLimiting
リクエスト・ポリシーの詳細は、APIゲートウェイ・バック・エンドへのリクエストの数の制限を参照してください。
-
-
APIデプロイメント仕様の個々のルートに適用するリクエスト・ポリシーを追加するには:
-
ルートの
backend
セクションの後にrequestPolicies
セクションを挿入します。例:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": {} } ] }
-
requestPolicies
セクションにリクエスト・ポリシーを含めます。たとえば、特定のルートのAPIデプロイメントのCORSサポートを有効にするには、
requestPolicies
セクションにcors
ポリシーを次のように含めます:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "cors":{ "allowedOrigins": ["*", "https://oracle.com"], "allowedMethods": ["*", "GET"], "allowedHeaders": [], "exposedHeaders": [], "isAllowCredentialsEnabled": false, "maxAgeInSeconds": 3000 } } } ] }
cors
リクエスト・ポリシーの詳細は、CORSサポートをAPIデプロイメントに追加を参照してください。
-
-
APIデプロイメント仕様の個々のルートに適用するレスポンス・ポリシーを追加するには:
-
ルートの
backend
セクションの後にresponsePolicies
セクションを挿入します。例:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": {} } ] }
-
responsePolicies
セクションにレスポンス・ポリシーを含めます。たとえば、特定のルートからのレスポンスで
X-Username
ヘッダーの名前をX-User-ID
に変更するには、次に示すようにresponsePolicies
セクションにheaderTransformations
ポリシーを含めます:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations": { "renameHeaders": { "items": [ { "from": "X-Username", "to": "X-User-ID" } ] } } } } ] }
headerTransformations
レスポンス・ポリシーの詳細は、ヘッダー変換レスポンス・ポリシーを追加するためのJSONファイルの編集を参照してください。
-
- APIデプロイメント仕様を含むJSONファイルを保存します。
-
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- JSONファイルをコンソールで「既存のAPIのアップロード」オプションで指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照してください。