ヘッダー変換リクエスト・ポリシーの追加

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

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

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

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

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

リクエストに含めるヘッダーを制限するには、次を指定します:

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

(元の値を保持したまま)リクエストに含まれるヘッダーの名前を変更するには、次を指定します:

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

リクエストに新しいヘッダーを追加する(またはリクエストにすでに含まれている既存のヘッダーの値を変更または保持する)には、次を指定します:

• アクション: 設定。

• 動作: ヘッダーがすでに存在する場合は、ヘッダーの既存の値で何を行うかを指定します:

  • 上書き: ヘッダーの既存の値を指定した値に置き換えます。
  • 追加: 指定した値をヘッダーの既存の値に追加します。
  • スキップ: ヘッダーの既存の値を保持します。
• ヘッダー名:リクエストに追加する(または値を変更)ヘッダーの名前。指定する名前は大/小文字が区別されず(大文字の使用は無視されます)、ルートの他の変換リクエスト・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、X-Api-Keyです。
• 値: 新しいヘッダーの値(または動作の設定に応じて既存のヘッダーの値に置換または追加する値)。複数の値を指定できます。指定する値には、単純な文字列を指定することも、${...}デリミタで囲まれたコンテキスト変数を含めることもできます(request.bodyを除く)。たとえば、"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": {}
    }
  ]
}

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

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

リクエストに含まれるヘッダーを制限するには、filterHeadersヘッダー変換リクエスト・ポリシーを指定します:

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

ここでは:

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

filterHeadersヘッダー変換リクエスト・ポリシーでは、最大50個のヘッダーを削除および許可できます。

例:

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

この例では、APIゲートウェイはすべての受信リクエストからUser-Agentヘッダーを削除します。

リクエストに含まれるヘッダーの名前を(元の値を保持しながら)変更するには、renameHeadersヘッダー変換リクエスト・ポリシーを指定します:

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

ここでは:

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

renameHeadersヘッダー変換リクエスト・ポリシーでは、最大20個のヘッダーを名前変更できます。

例:

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

この例では、APIゲートウェイは、ヘッダーの元の値を保持しながら、X-Usernameヘッダーの名前をX-User-IDに変更します。

リクエストに新しいヘッダーを追加する(またはリクエストにすでに含まれている既存のヘッダーの値を変更または保持する)には、setHeadersヘッダー変換リクエスト・ポリシーを指定します:

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

ここでは:

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

  最大10個の値を指定できます。複数の値を指定した場合、APIゲートウェイは値ごとにヘッダーを追加します。

• "ifExists": "<OVERWRITE|APPEND|SKIP>"は、<header-name>で指定されたヘッダーがすでに存在する場合に、ヘッダーの既存の値に対して実行する処理を示します:

  • ヘッダーの既存の値を指定した値に置き換えるには、OVERWRITEを使用します。
  • 指定した値をヘッダーの既存の値に追加するには、APPENDを使用します。
  • ヘッダーの既存の値を保持するには、SKIPを使用します。

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

setHeadersヘッダー変換リクエスト・ポリシーでは、最大20個のヘッダーを追加(またはその値を変更)できます。

例:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerTransformations": {
          "setHeaders": {
            "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ゲートウェイの更新を参照してください