Oracle Cloud Infrastructureドキュメント

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デプロイメント仕様に追加するには:

  1. コンソールを使用してAPIデプロイメントを作成または更新し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。

    詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。

  2. 「基本情報」ページの「APIリクエスト・ポリシー」セクションで、APIデプロイメント仕様のすべてのルートにグローバルに適用するリクエスト・ポリシーを指定します:

    • 相互TLS:リクエストを行うAPIクライアントによって提示されたTLS証明書に基づいてAPIゲートウェイにデプロイするAPIへのアクセスを制御するポリシー。mTLSポリシーは、APIデプロイメント仕様のすべてのルートにのみグローバルに適用できます(個々のルートには適用できません)。「APIデプロイメントへのmTLSサポートの追加」を参照してください。
    • CORS: APIゲートウェイにデプロイするAPIでCORSサポートを有効化するポリシー。APIデプロイメント仕様の個々のルートに適用するCORSポリシーも指定できます(最初にグローバルCORSポリシーを入力する必要はありません)。CORSサポートをAPIデプロイメントに追加を参照してください。
    • レート制限: APIクライアントがバックエンド・サービスにリクエストを行うことのできるレートを制限するポリシー。APIデプロイメント仕様の(個々のルートではなく)すべてのルートにのみグローバルにレート制限ポリシーを適用できます。APIゲートウェイ・バック・エンドへのリクエストの数の制限を参照してください。

  3. 「次へ」をクリックして、「認証」ページでグローバル認証リクエスト・ポリシーを定義するオプションを指定します。

    認証リクエスト・ポリシーは、APIゲートウェイにデプロイするAPIへのアクセスを制御します。最初にグローバル認証ポリシーを指定すると、APIデプロイメント仕様の個々のルートに適用する認可ポリシーを指定できます。APIデプロイメントへの認証と認可の追加を参照してください。

  4. 「次」をクリックして、「ルート」ページのAPIデプロイメント内の個々のルートの詳細を入力します。

  5. 個々のルートに適用するリクエスト・ポリシーを指定するには、「リクエスト・ポリシーのルーティングを表示」をクリックして、次を指定します:

  6. 個々のルートに適用するレスポンス・ポリシーを指定するには、「ルート・レスポンス・ポリシーの表示」をクリックして、次を指定します:

  7. 「次」をクリックして、APIデプロイメント用に入力した詳細を確認します。
  8. APIデプロイメントを作成または更新するには、「作成」または「変更の保存」をクリックします。
  9. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

リクエスト・ポリシーおよびレスポンス・ポリシーを追加するためのJSONファイルの編集

JSONファイルのAPIデプロイメント仕様にリクエスト・ポリシーおよびレスポンス・ポリシーを追加するには:

  1. 任意のJSONエディタを使用して、リクエスト・ポリシーまたはレスポンス・ポリシーを追加する既存のAPIデプロイメント仕様を編集するか、新しいAPIデプロイメント仕様を作成します(APIデプロイメント仕様の作成を参照)。

    APIデプロイメント仕様には、少なくとも次の内容を含むroutesセクションが含まれます:

    • パス。たとえば、/helloです
    • 1つ以上のメソッド。たとえば、GETです
    • バック・エンドの定義。たとえば、URLまたはOCI Functions内のファンクションのOCIDです。

    たとえば、次の基本的なAPIデプロイメント仕様では、OCI Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバックエンドとして定義しています:

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

  2. APIデプロイメント仕様内のすべてのルートにグローバルに適用するリクエスト・ポリシーを追加するには:

    1. routesセクションの前にrequestPoliciesセクションを挿入します。例:

      
{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

    2. 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ゲートウェイ・バック・エンドへのリクエストの数の制限を参照してください。

  3. APIデプロイメント仕様の個々のルートに適用するリクエスト・ポリシーを追加するには:

    1. ルートのbackendセクションの後にrequestPoliciesセクションを挿入します。例:

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}

    2. 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デプロイメントに追加を参照してください。

  4. APIデプロイメント仕様の個々のルートに適用するレスポンス・ポリシーを追加するには:

    1. ルートのbackendセクションの後にresponsePoliciesセクションを挿入します。例:

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {}
    }
  ]
}

    2. 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ファイルの編集を参照してください。

  5. APIデプロイメント仕様を含むJSONファイルを保存します。

  6. APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:

    • 「既存のAPIのアップロード」オプションを選択して、コンソールでJSONファイルを指定します
    • APIゲートウェイREST APIへのリクエストでJSONファイルを指定します

    詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照してください。