Oracle Cloud Infrastructureドキュメント

受信リクエストおよび送信レスポンスの変換

API Gatewayを使用してバックエンド・サービスとの間で送受信される受信リクエストおよび送信レスポンスを変更する方法をご紹介します。

多くの場合、APIゲートウェイでは、受信リクエストをバックエンド・サービスに送信する前に変更する必要があります。同様に、APIゲートウェイでバックエンド・サービスから返されたレスポンスを変更することが必要な場合があります。例:

  • バックエンド・サービスでは、特定のHTTPヘッダーのセット(たとえば、Accept-LanguageやAccept-Encoding)を含むリクエストが必要になる場合があります。APIコンシューマおよびAPIクライアントに対してこの実装の詳細を非表示にするには、APIゲートウェイを使用して必要なヘッダーを追加します。
  • 多くの場合、Webサーバーではレスポンス・ヘッダーに完全なバージョン情報が含まれます。セキュリティ上の理由から、APIコンシューマおよびAPIクライアントに基礎となるテクノロジ・スタックを知られないようにすることが必要な場合もあります。APIゲートウェイを使用して、サーバー・ヘッダーをレスポンスから削除できます。
  • バックエンド・サービスでは、レスポンスに機密情報が含まれる場合があります。APIゲートウェイを使用して、このような情報を削除できます。

APIゲートウェイを使用して、次のことができます:

  • リクエストおよびレスポンスのヘッダーを追加、削除および変更します。
  • リクエストの問合せパラメータを追加、削除および変更します。
  • レガシー・アプリケーションおよび移行をサポートするために、リクエストURLをパブリック形式から内部形式に書き換えます。

リクエストおよびレスポンス・ポリシーを使用して、受信リクエストのヘッダーと問合せパラメータ、および送信レスポンスのヘッダーを変換します(APIデプロイメント仕様へのリクエスト・ポリシーとレスポンス・ポリシーの追加を参照)。

ヘッダーおよび問合せパラメータの変換リクエストおよびレスポンス・ポリシーにコンテキスト変数を含めることができます。コンテキスト変数を含めると、他のヘッダー、問合せパラメータ、パス・パラメータおよび認証パラメータの値を使用して、ヘッダーおよび問合せパラメータを変更できます。コンテキスト変数値の値は元のリクエストまたはレスポンスから抽出され、APIゲートウェイは変換ポリシーを使用してリクエストまたはレスポンスを評価するため、その後更新されないことに注意してください。コンテキスト変数の詳細は、ポリシーおよびHTTPバック・エンド定義へのコンテキスト変数の追加を参照してください。

ヘッダーまたは問合せパラメータの変換リクエストまたはレスポンス・ポリシーによって無効なヘッダーまたは問合せパラメータが生成される場合、変換ポリシーは無視されます。

ヘッダー変換ポリシーを使用して、特定の保護されたリクエストおよびレスポンス・ヘッダーを変換することはできません。保護されたリクエスト・ヘッダーおよびレスポンス・ヘッダーを参照してください。

次の方法で、ヘッダーおよび問合せパラメータの変換リクエストおよびレスポンス・ポリシーをAPIデプロイメント仕様に追加できます:

  • コンソールの使用
  • JSONファイルの編集

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

ヘッダー変換リクエスト・ポリシーをAPIデプロイメント仕様に追加するには、コンソールを使用するか、JSONファイルを編集します。

ヘッダー変換ポリシーを使用して、特定の保護されたリクエスト・ヘッダーを変換することはできません。保護されたリクエスト・ヘッダーおよびレスポンス・ヘッダーを参照してください。

コンソールを使用したヘッダー変換リクエスト・ポリシーの追加

コンソールを使用してヘッダー変換リクエスト・ポリシーをAPIデプロイメント仕様に追加するには:

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

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

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

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

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

  4. 「ルート」ページで、ヘッダー変換リクエスト・ポリシーを指定するルートを選択します。
  5. 「ルート・リクエスト・ポリシーの表示」を選択します。
  6. 「ヘッダー変換」の横にある「追加」ボタンを選択して、現在のルートのAPIゲートウェイへのリクエストに含まれるヘッダーを更新します。

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

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

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

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

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

    • アクション: 設定。

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

      • 上書き: ヘッダーの既存の値を指定した値に置き換えます。
      • 追加: 指定した値をヘッダーの既存の値に追加します。
      • スキップ: ヘッダーの既存の値を保持します。
    • 名前: リクエストに追加(または値を変更)するヘッダーの名前。指定する名前は大/小文字が区別されず(大文字の使用は無視されます)、ルートの他の変換リクエスト・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、X-Api-Keyです。
    • 値: 新しいヘッダーの値(または動作の設定に応じて既存のヘッダーの値に置換または追加する値)。複数の値を指定できます。指定する値には、単純な文字列を指定することも、${...}区切り文字で囲まれたコンテキスト変数(request.bodyを除く)を含めることもできます。たとえば、"value": "zyx987wvu654tsu321"、"value": "${request.path[region]}"、"value": "${request.headers[opc-request-id]}"です。
  10. 「変更の保存」を選択し、「次」を選択して個々のルートに入力した詳細を確認します。
  11. APIデプロイメントを作成または更新するには、「作成」または「変更の保存」を選択します。
  12. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

ヘッダー変換リクエスト・ポリシーを追加するためのJSONファイルの編集

JSONファイルのAPIデプロイメント仕様にヘッダー変換リクエスト・ポリシーを追加するには:

  1. 任意の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"
      }
    }
  ]
}

  2. ヘッダー変換リクエスト・ポリシーを適用するルートのbackendセクションの後にrequestPoliciesセクションを挿入します。例:

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

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

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

  4. リクエストに含まれるヘッダーを制限するには、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ヘッダーを削除します。

  5. リクエストに含まれるヘッダーの名前を(元の値を保持しながら)変更するには、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に変更します。

  6. リクエストに新しいヘッダーを追加する(またはリクエストにすでに含まれている既存のヘッダーの値を変更または保持する)には、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に置き換えます。

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

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

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

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

  9. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

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

問合せパラメータ変換リクエスト・ポリシーをAPIデプロイメント仕様に追加するには、コンソールを使用するか、JSONファイルを編集します。

コンソールを使用した問合せパラメータ変換リクエスト・ポリシーの追加

コンソールを使用して問合せパラメータ変換リクエスト・ポリシーをAPIデプロイメント仕様に追加するには:

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

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

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

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

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

  4. 「ルート」ページで、問合せパラメータ変換リクエスト・ポリシーを指定するルートを選択します。
  5. 「ルート・リクエスト・ポリシーの表示」を選択します。
  6. 「問合せパラメータ変換」の横にある「追加」ボタンを選択して、現在のルートのAPIゲートウェイへのリクエストに含まれる問合せパラメータを更新します。

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

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

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

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

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

    • アクション: 設定。

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

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

問合せパラメータ変換リクエスト・ポリシーを追加するためのJSONファイルの編集

JSONファイルのAPIデプロイメント仕様に問合せパラメータ変換リクエスト・ポリシーを追加するには:

  1. 任意の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"
      }
    }
  ]
}

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

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

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

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

  4. リクエストに含まれる問合せパラメータを制限するには、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問合せパラメータを削除します。

  5. リクエストに含まれる問合せパラメータの名前を(元の値を保持しながら)変更するには、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に変更します。

  6. リクエストに新しい問合せパラメータを追加する(またはリクエストにすでに含まれている既存の問合せパラメータの値を変更または保持する)には、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に置き換えます。

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

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

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

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

  9. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

ヘッダー変換レスポンス・ポリシーの追加

ヘッダー変換レスポンス・ポリシーをAPIデプロイメント仕様に追加するには、コンソールを使用するか、JSONファイルを編集します。

ヘッダー変換ポリシーを使用して、特定の保護されたレスポンス・ヘッダーを変換することはできません。保護されたリクエスト・ヘッダーおよびレスポンス・ヘッダーを参照してください。

コンソールを使用したヘッダー変換レスポンス・ポリシーの追加

コンソールを使用してヘッダー変換レスポンス・ポリシーをAPIデプロイメント仕様に追加するには:

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

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

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

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

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

  4. 「ルート」ページで、ヘッダー変換レスポンス・ポリシーを指定するルートを選択します。
  5. 「ルート・レスポンス・ポリシーの表示」を選択します。
  6. 「ヘッダー変換」の横にある「追加」ボタンを選択して、現在のルートのAPIゲートウェイからのレスポンスに含まれるヘッダーを更新します。

  7. レスポンスに含めるヘッダーを制限するには、次を指定します:

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

  8. (元の値を保持したまま)レスポンスに含まれるヘッダーの名前を変更するには、次を指定します:

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

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

    • アクション: 設定。

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

      • 上書き: ヘッダーの既存の値を指定した値に置き換えます。
      • 追加: 指定した値をヘッダーの既存の値に追加します。
      • スキップ: ヘッダーの既存の値を保持します。
    • 名前: レスポンスに追加(または値を変更)するヘッダーの名前。指定する名前は大/小文字が区別されず、ルートの他の変換レスポンス・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、X-Api-Keyです。
    • 値: 新しいヘッダーの値(または動作の設定に応じて既存のヘッダーの値に置換または追加する値)。指定する値には、単純な文字列を指定することも、${...}デリミタで囲まれたコンテキスト変数を含めることもできます。たとえば、"value": "zyx987wvu654tsu321"です。複数の値を指定できます。
  10. 「変更の保存」を選択し、「次」を選択して個々のルートに入力した詳細を確認します。
  11. APIデプロイメントを作成または更新するには、「作成」または「変更の保存」を選択します。
  12. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

ヘッダー変換レスポンス・ポリシーを追加するためのJSONファイルの編集

JSONファイルのAPIデプロイメント仕様にヘッダー変換レスポンス・ポリシーを追加するには:

  1. 任意の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"
      }
    }
  ]
}

  2. ヘッダー変換レスポンス・ポリシーを適用するルートのbackendセクションの後にresponsePoliciesセクションを挿入します。例:

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

  3. headerTransformationsセクションをresponsePoliciesセクションに追加します。

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

  4. レスポンスに含まれるヘッダーを制限するには、filterHeadersヘッダー変換レスポンス・ポリシーを指定します:

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "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ヘッダー変換レスポンス・ポリシーでは、最大20個のヘッダーを削除および許可できます。

    例:

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

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

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

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "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"
      },
      "responsePolicies": {
        "headerTransformations": {
          "renameHeaders": {
            "items": [
              {
                "from": "X-Username",
                "to": "X-User-ID"
              }
            ]
          }
        }
      }
    }
  ]
}

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

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

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "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>"の設定に応じて既存のヘッダーの値に置換または追加する値)です。指定する値には、単純な文字列を指定することも、${...}デリミタで囲まれたコンテキスト変数を含めることもできます。たとえば、"values": "zyx987wvu654tsu321"です。

      最大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"
      },
      "responsePolicies": {
        "headerTransformations": {
          "setHeaders": {
            "items": [
              {
                "name": "X-Api-Key",
                "values": ["zyx987wvu654tsu321"],
                "ifExists": "OVERWRITE"
              }
            ]
          }
        }
      }
    }
  ]
}

    この例では、APIゲートウェイはすべての送信レスポンスにX-Api-Key:zyx987wvu654tsu321ヘッダーを追加します。送信レスポンスのX-Api-Keyヘッダーがすでに別の値に設定されている場合、APIゲートウェイは既存の値をzyx987wvu654tsu321に置き換えます。

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

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

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

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

  9. (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

例

このセクションの例では、JSONファイルの次のAPIデプロイメント定義および基本的なAPIデプロイメント仕様を想定しています:

{
  "displayName": "Marketing Deployment",
  "gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
  "pathPrefix": "/marketing",
  "specification": {
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov"
        },
        "requestPolicies": {}
      }
    ]
  },
  "freeformTags": {},
  "definedTags": {}
}

コンソールでダイアログを使用してAPIデプロイメント仕様を定義する場合も、例が適用されます。

例1: ヘッダー・パラメータを問合せパラメータに変換する

この例では、既存のHTTPバック・エンドが、ヘッダー・パラメータではなく問合せパラメータを含むリクエストのみを処理すると仮定します。しかし、HTTPバック・エンドでヘッダー・パラメータを含むリクエストを処理する必要があります。これを実現するには、リクエスト・ヘッダーから取得した値を問合せパラメータとしてHTTPバック・エンドに渡す問合せパラメータ変換リクエスト・ポリシーを含むAPIデプロイメント仕様を作成します。

        "requestPolicies": {
          "queryParameterTransformations":  {
            "setQueryParameters": {
              "items": [
                {
                  "name": "region",
                  "values": ["${request.headers[region]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

この例では、curl -H "region: west" https://<gateway-hostname>/marketing/weatherのようなリクエストがhttps://api.weather.gov?region=westに解決されます。

例2: あるヘッダーから別のヘッダーに変換する

この例では、既存のHTTPバック・エンドが特定のヘッダーを含むリクエストのみを処理すると仮定します。しかし、HTTPバック・エンドで別のヘッダーを含むリクエストを処理する必要があります。これを実現するには、あるリクエスト・ヘッダーから取得した値を別のリクエスト・ヘッダーとしてHTTPバック・エンドに渡すヘッダー変換リクエスト・ポリシーを含むAPIデプロイメント仕様を作成します。

        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "region",
                  "values": ["${request.headers[locale]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

この例では、curl -H "locale: west" https://<gateway-hostname>/marketing/weatherのようなリクエストがリクエストcurl -H "region: west" https://api.weather.govに解決されます。

例3: JWTから取得した認証パラメータをリクエスト・ヘッダーとして追加する

この例では、既存のHTTPバック・エンドで、検証済JSON Webトークン(JWT)のsubクレームの値をJWT_SUBJECTという名前のヘッダーとしてリクエストに含める必要があると仮定します。APIゲートウェイ・サービスは、JWTに含まれるsubクレームの値を認証パラメータとしてrequest.auth表に保存しました。

JWT_SUBJECTという名前のヘッダーにsubの値を含めるには、ヘッダー変換リクエスト・ポリシーを含むAPIデプロイメント仕様を作成します。リクエスト・ポリシーは、request.auth表からsub値を取得し、それをJWT_SUBJECTヘッダーの値としてHTTPバック・エンドに渡します。

        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "JWT_SUBJECT",
                  "values": ["${request.auth[sub]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

この例では、リクエストが正常に検証されると、HTTPバック・エンドに渡されるリクエストにJWT_SUBJECTヘッダーが追加されます。

例4: 認可プロバイダ・ファンクションから取得したキーを問合せパラメータとして追加する

この例では、既存のHTTPバック・エンドで、認証の目的でリクエストにaccess_keyという問合せパラメータを含める必要があると仮定します。access_key問合せパラメータに、リクエストを正常に検証した認可プロバイダ・ファンクションによって戻されたapiKeyという名前のキーの値を指定する必要があります。APIゲートウェイ・サービスは、apiKey値を認証パラメータとしてrequest.auth表に保存しました。

リクエストにaccess_key問合せパラメータを含めるには、問合せパラメータ変換リクエスト・ポリシーを含むAPIデプロイメント仕様を作成します。リクエスト・ポリシーは、request.auth表からapiKey値を取得し、それをaccess_key問合せパラメータの値としてHTTPバック・エンドに渡します。

        "requestPolicies": {
          "queryParameterTransformations": {
            "setQueryParameters": {
              "items": [
                {
                  "name": "access_key",
                  "values": ["${request.auth[apiKey]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

この例では、access_key問合せパラメータは、HTTPバック・エンドに渡されるリクエストに、request.auth表のapiKey値とともに追加されます。https://<gateway-hostname>/marketing/weatherなどのリクエストは、https://api.weather.gov?access_key=fw5n9abi0epなどのリクエストに解決されます

例5: オプションの問合せパラメータのデフォルト値を追加する

この例では、既存のHTTPバック・エンドで、リクエストにcountryという問合せパラメータを含める必要があると仮定します。ただし、country問合せパラメータはオプションで、一部のAPIクライアント送信リクエストには含まれません。リクエストにすでにcountry問合せパラメータと値が含まれている場合は、両方をそのままHTTPバック・エンドに渡します。ただし、リクエストにcountry問合せパラメータがまだ含まれていない場合は、country問合せパラメータとデフォルト値をリクエストに追加します。

すべてのリクエストにcountry問合せパラメータが含まれるようにするには、問合せパラメータ変換リクエスト・ポリシーを含むAPIデプロイメント仕様を作成します。リクエスト・ポリシーは、country問合せパラメータがまだ含まれていないリクエストに、country問合せパラメータとデフォルト値を追加します。

        "requestPolicies": {
          "queryParameterTransformations": {
            "setQueryParameters": {
              "items": [
                {
                  "name": "country",
                  "values": ["usa"],
                  "ifExists": "SKIP"
                }
              ]
            }
          }
        }

この例では、https://<gateway-hostname>/marketing/weatherのようなリクエストがhttps://api.weather.gov?country=usaに解決されます。https://<gateway-hostname>/marketing/weather?country=canadaのようなリクエストはhttps://api.weather.gov?country=canadaに解決されます。

保護されたリクエスト・ヘッダーとレスポンス・ヘッダー

次のように、ヘッダー変換ポリシーを使用して、特定の保護されたリクエストおよびレスポンス・ヘッダーを変換することはできません。

ヘッダー リクエスト・ヘッダーとして保護 レスポンス・ヘッダーとして保護
access-control-allow-credentials 適用なし はい
access-control-allow-headers 適用なし はい
access-control-allow-methods 適用なし はい
access-control-allow-origin 適用なし はい
access-control-expose-headers 適用なし はい
access-control-max-age 適用なし はい
CDNループ はい 適用なし
接続 はい はい
content-length はい はい
Cookie はい 適用なし
除外 はい はい
keep-alive はい はい
opc-request-id はい はい
オリジン はい 適用なし
プロキシ認証 適用なし はい
プロキシ認可 はい 適用なし
public-key-pins 適用なし はい
再試行後 適用なし はい
strict-transport-security 適用なし はい
ティー はい はい
トレーラ 適用なし はい
転送エンコーディング はい はい
アップグレード はい はい
x-content-type-options 適用なし はい
x-forwarded-for はい 適用なし
xフレーム・オプション 適用なし はい
x-real-ip はい 適用なし
x-xss-protection 適用なし はい