問合せパラメータ変換リクエスト・ポリシーの追加

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

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

「次へ」を選択し、「認証」ページで認証オプションを指定します。

認証オプションの詳細は、APIデプロイメントへの認証と認可の追加に関する項を参照してください。

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

リクエストに含める問合せパラメータを制限するには、次を指定します:

• アクション: フィルタ。
• タイプ: 「ブロック」を選択して明示的にリストした問合せパラメータをリクエストから削除するか、「許可」を選択して明示的にリストした問合せパラメータのみをリクエストで許可します(他の問合せパラメータはリクエストから削除されます)。
• 問合せパラメータの名前:リクエストから削除するか、リクエストで許可する問合せのパラメータのリスト(タイプの設定によって異なります)。指定する名前は大/小文字が区別され、ルートの他の変換リクエスト・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、User-Agentです。

(元の値を保持したまま)リクエストに含まれる問合せパラメータの名前を変更するには、次を指定します:

• アクション: 名前の変更。
• クエリー・パラメータ名:名前を変更するクエリー・パラメータの元の名前。指定する名前は大/小文字が区別され、ルートの他の変換リクエスト・ポリシーに含めることはできません。たとえば、X-Usernameです。
• 新しい問合せパラメータ名:名前を変更する問合せパラメータの名前の新しい名前。指定する名前は大/小文字が区別され(大文字の使用は尊重されます)、ルートの他の変換リクエスト・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、X-User-IDです。

リクエストに新しい問合せパラメータを追加する(またはリクエストにすでに含まれている既存の問合せパラメータの値を変更または保持する)には、次を指定します:

• アクション: 設定。

• 動作: 問合せパラメータがすでに存在する場合は、問合せパラメータの既存の値で何を行うかを指定します:

  • 上書き: 問合せパラメータの既存の値を指定した値に置き換えます。
  • 追加: 指定した値を問合せパラメータの既存の値に追加します。
  • スキップ: 問合せパラメータの既存の値を保持します。
• 問合せパラメータ名: リクエストに追加する(または値を変更)問合せパラメータの名前です。指定する名前は大/小文字が区別され、ルートの他の変換リクエスト・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、X-Api-Keyです。
• 値: 新しい問合せパラメータの値(または動作の設定に応じて既存の問合せパラメータの値に置換または追加する値)。指定する値には、単純な文字列を指定することも、${...}デリミタで囲まれたコンテキスト変数を含めることもできます。たとえば、"value": "zyx987wvu654tsu321"、"value": "${request.path[region]}"、"value": "${request.headers[opc-request-id]}"です。複数の値を指定できます。

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

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

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

問合せパラメータ変換リクエスト・ポリシーを適用するルートのbackendセクションの後にrequestPoliciesセクションを挿入します。例:

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

queryParameterTransformationsセクションをrequestPoliciesセクションに追加します。

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

リクエストに含まれる問合せパラメータを制限するには、filterQueryParameters問合せパラメータ変換リクエスト・ポリシーを指定します:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterTransformations": {
          "filterQueryParameters": {
            "type": "<BLOCK|ALLOW>",
            "items": [
              {
                "name": "<query-parameter-name>"
              }
            ]
          }
        }
      }
    }
  ]
}

ここでは:

• "type": "<BLOCK|ALLOW>"は、"items":[{"name":"<query-parameter-name>"}]で指定された問合せパラメータに対して実行する処理を示します:
  • BLOCKを使用して、明示的にリストした問合せパラメータをリクエストから削除します。
  • ALLOWを使用して、明示的にリストした問合せパラメータのみをリクエストで許可します(他の問合せパラメータはリクエストから削除されます)。
• "name":"<query-parameter-name>は、("type": "<BLOCK|ALLOW>"の設定に応じて)リクエストから削除するか、リクエストで許可する問合せパラメータです。指定する名前は大/小文字が区別され、ルートの他の変換リクエスト・ポリシーに含めることはできません(ALLOWリスト内の項目を除く)。たとえば、User-Agentです。

filterQueryParameters問合せパラメータ変換リクエスト・ポリシーでは、最大50個の問合せパラメータを削除および許可できます。

例:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterTransformations": {
          "filterQueryParameters": {
            "type": "BLOCK",
            "items": [
              {
                "name": "User-Agent"
              }
            ]
          }
        }
      }
    }
  ]
}

この例では、APIゲートウェイはすべての受信リクエストからUser-Agent問合せパラメータを削除します。

リクエストに含まれる問合せパラメータの名前を(元の値を保持しながら)変更するには、renameQueryParameters問合せパラメータ変換リクエスト・ポリシーを指定します:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterTransformations": {
          "renameQueryParameters": {
            "items": [
              {
                "from": "<original-name>",
                "to": "<new-name>"
              }
            ]
          }
        }
      }
    }
  ]
}

ここでは:

• "from": "<original-name>"は、名前を変更する問合せパラメータの元の名前です。指定する名前は大/小文字が区別され、ルートの他の変換リクエスト・ポリシーに含めることはできません。たとえば、X-Usernameです。
• "to": "<new-name>"は、名前を変更する問合せパラメータの新しい名前です。指定する名前は大/小文字が区別され(大文字の使用は尊重されます)、ルートの他の変換リクエスト・ポリシーに含めることはできません(ALLOWリストの項目を除く)。たとえば、X-User-IDです。

renameQueryParameters問合せパラメータ変換リクエスト・ポリシーでは、最大20個の問合せパラメータの名前を変更できます。

例:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterTransformations": {
          "renameQueryParameters": {
            "items": [
              {
                "from": "X-Username",
                "to": "X-User-ID"
              }
            ]
          }
        }
      }
    }
  ]
}

この例では、APIゲートウェイは、問合せパラメータの元の値を保持しながら、X-Username問合せパラメータの名前をX-User-IDに変更します。

リクエストに新しい問合せパラメータを追加する(またはリクエストにすでに含まれている既存の問合せパラメータの値を変更または保持する)には、setQueryParameters問合せパラメータ変換リクエスト・ポリシーを指定します:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterTransformations": {
          "setQueryParameters": {
            "items": [
              {
                "name": "<query-parameter-name>",
                "values": ["<query-parameter-value>"],
                "ifExists": "<OVERWRITE|APPEND|SKIP>"
              }
            ]
          }
        }
      }
    }
  ]
}

ここでは:

• "name": "<query-parameter-name>"は、リクエストに追加(または値を変更)する問合せパラメータの名前です。指定する名前は大/小文字が区別され、ルートの他の変換リクエスト・ポリシーに含めることはできません(ALLOWリスト内の項目を除く)。たとえば、X-Api-Keyです。
• "values": ["<query-parameter-value>"]は、新しい問合せパラメータの値(または、"ifExists": "<OVERWRITE|APPEND|SKIP>"の設定に応じて既存の問合せパラメータの値に置換または追加する値)です。指定する値には、単純な文字列を指定することも、${...}デリミタで囲まれたコンテキスト変数を含めることもできます。たとえば、"values": "zyx987wvu654tsu321"、"values": "${request.path[region]}"、"values": "${request.headers[opc-request-id]}"です。

  最大10個の値を指定できます。複数の値を指定した場合、APIゲートウェイは値ごとに問合せパラメータを追加します。

• "ifExists": "<OVERWRITE|APPEND|SKIP>"は、<query-parameter-name>で指定された問合せパラメータがすでに存在する場合に、問合せパラメータの既存の値に対して実行する処理を示します:

  • OVERWRITEを使用して、問合せパラメータの既存の値を指定した値に置き換えます。
  • APPENDを使用して、指定した値を問合せパラメータの既存の値に追加します。
  • SKIPを使用して、問合せパラメータの既存の値を保持します。

  指定しない場合、デフォルトはOVERWRITEです。

setQueryParameters問合せパラメータ変換リクエスト・ポリシーでは、最大20個の問合せパラメータを追加(またはその値を変更)できます。

例:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterTransformations": {
          "setQueryParameters": {
            "items": [
              {
                "name": "X-Api-Key",
                "values": ["zyx987wvu654tsu321"],
                "ifExists": "OVERWRITE"
              }
            ]
          }
        }
      }
    }
  ]
}

この例では、APIゲートウェイはすべての受信リクエストにX-Api-Key:zyx987wvu654tsu321問合せパラメータを追加します。受信リクエストのX-Api-Key問合せパラメータがすでに別の値に設定されている場合、APIゲートウェイは既存の値をzyx987wvu654tsu321に置き換えます。

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

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

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