リクエスト要素に基づくAPIゲートウェイ・バック・エンドの動的選択

例1: ホストによるバックエンドの選択

APIデプロイメントを構成して、元のリクエストの送信先ホスト(リクエストのホスト・ヘッダーのホスト・フィールドから抽出)に基づいてバックエンドを動的に選択できます。この設計により、様々なテナントをサポートするAPIゲートウェイを定義できます。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.host"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "cars.example.com"
              ],
              "isDefault": "true",
              "name": "car-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "minivans.examplecloud.com",
                "trucks.example.com"
              ],
              "name": "truck-minivan-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}

この例では、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、次のように、元のリクエストが送信されたホスト(リクエストのホスト・ヘッダーのホスト・フィールドから抽出されたホスト)によって異なります。

• リクエストがcars.example.comに送信された場合、リクエストはhttp://cars-api.example.comにルーティングされます。
• リクエストがminivans.examplecloud.comまたはtrucks.example.comに送信された場合、リクエストはOCIファンクションのサーバーレス・ファンクション・バック・エンドにルーティングされます。
• リクエストが別のホストに送信された場合、リクエストはデフォルトでhttp://cars-api.example.comにルーティングされます。

例2: ホスト・サブドメインによるバックエンドの選択

APIデプロイメントを構成して、元のリクエストが送信されたホスト文字列のサブドメインに基づいてバックエンドを動的に選択できます。ホスト文字列は、リクエストのホスト・ヘッダーから抽出され、指定した文字列でマスクされ、リクエストのルーティングに使用されるサブドメインが残ります。この設計により、様々なテナントをサポートするAPIゲートウェイを定義できます。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.subdomain[example.com]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "cars"
              ],
              "isDefault": "true",
              "name": "car-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "minivans",
                "trucks"
              ],
              "name": "truck-minivan-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}

この例では、次のように、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、元のリクエストが送信されたホスト・サブドメインによって異なります。

• リクエストがcars.example.comに送信された場合、リクエストはhttp://cars-api.example.comにルーティングされます
• リクエストがminivans.example.comまたはtrucks.example.comに送信された場合、リクエストはOCI関数のサーバーレス・ファンクション・バック・エンドにルーティングされます
• リクエストがexample.comの別のサブドメイン(car.example.comやsedan.example.comなど)に送信された場合、リクエストはデフォルトでhttp://cars-api.example.comにルーティングされます。

例3a: ホスト・サブドメインでバックエンドを選択します(バックエンドURLのホスト名を変更し、一致タイプANY_OFを使用)。

APIデプロイメントを構成して、元のリクエストが送信されたホスト文字列のサブドメインに基づいてバックエンドを動的に選択できます。ホスト文字列は、リクエストのホスト・ヘッダーから抽出され、指定した文字列でマスクされ、リクエストのルーティングに使用されるサブドメインが残されます。追加の検証では、サブドメイン・マスクをバックエンドURLにコンテキスト変数として含めることで、リクエストが公開するバックエンドにのみルーティングされるようにできます。一致タイプとしてANY_OFを指定した場合、コンテキスト変数の値にワイルドカードを含めることはできず、リクエストがバックエンドに送信されるように、routes.routingBackends.key値の1つと完全に一致する必要があります。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.subdomain[example.com]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "cars",
                "hatchbacks"
              ],
              "name": "car-hatchback-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://${request.subdomain[example.com]}-api.example.com"
            }
          }
        ]
      }
    }
  ]
}

この例では、次のように、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、元のリクエストが送信されたホスト・サブドメインによって異なります。

• リクエストがcars.example.comまたはhatchbacks.example.comに送信された場合、リクエストはhttp://cars-api.example.comまたはhttp://hatchbacks-api.example.comにルーティングされます。
• リクエストがexample.comの別のサブドメイン(suvs.example.comやsedans.example.comなど)に送信された場合、リクエストは失敗します。

この例に示すようにコンテキスト変数を含めることで、バックエンドURLのホスト名を変更することを検討している場合は、次の点に注意してください。

• バックエンドURLは、selectorに指定されたコンテキスト変数を使用してのみ変更できます。
• 許可されたバックエンドのリストを強制するには、ルールに"isDefault: "true"を設定しないでください。

例3b: ホスト・サブドメインでバックエンドを選択します(バックエンドURLのホスト名を変更し、一致タイプWILDCARDを使用)。

APIデプロイメントを構成して、元のリクエストが送信されたホスト文字列のサブドメインに基づいてバックエンドを動的に選択できます。ホスト文字列は、リクエストのホスト・ヘッダーから抽出され、指定した文字列でマスクされ、リクエストのルーティングに使用されるサブドメインが残されます。追加の検証では、サブドメイン・マスクをバックエンドURLにコンテキスト変数として含めることで、リクエストが公開するバックエンドにのみルーティングされるようにできます。一致タイプとしてWILDCARDを指定した場合、コンテキスト変数の値にはワイルドカードを含めることができ、リクエストがバックエンドに送信されるように、routes.routingBackends.key値のいずれかと一致する必要があります。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.subdomain[example.com]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "WILDCARD",
              "values": [
                "*s"
              ],
              "name": "domestic-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://${request.subdomain[example.com]}-api.example.com"
            }
          }
        ]
      }
    }
  ]
}

この例では、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、元のリクエストが送信されたホスト・サブドメインがワイルドカードを含むroutes.routingBackends.key値と一致するかどうかによって異なります。この場合、元のリクエストが文字's'で終わるホスト・サブドメインに送信されたかどうかは、次のようになります。

• リクエストが文字's'で終わるサブドメインに送信された場合、リクエストは適切にルーティングされます。たとえば、cars.example.com、hatchbacks.example.com、suvs.example.comまたはsedans.example.comに送信されたリクエストは、それぞれhttp://cars-api.example.com、http://hatchbacks-api.example.com、http://suvs-api.example.comまたはhttp://sedans-api.example.comにルーティングされます。
• リクエストが文字's'で終わらないサブドメインに送信された場合、リクエストは失敗します。たとえば、truck.example.comまたはtractor.example.comに送信されたリクエストは失敗します。

この例に示すようにコンテキスト変数を含めることで、バックエンドURLのホスト名を変更することを検討している場合は、次の点に注意してください。

• バックエンドURLは、selectorに指定されたコンテキスト変数を使用してのみ変更できます。
• ワイルドカードを使用する場合は、ワイルドカードを慎重に構成します。ワイルドカード構成が正しくないと、要求が意図しないバックエンドにルーティングされる可能性があります。たとえば、buses.example.comに送信されたリクエストは、想定どおりにhttp://buses-api.example.comに正しくルーティングされます。ただし、この構成では、最初にbus.example.comおよびs.example.comに送信されたリクエストがそれぞれhttp://bus-api.example.comおよびhttp://s-api.example.comにルーティングされ、いずれも意図されていませんでした。

例4: 使用プランによるバックエンドの選択

APIデプロイメントを構成して、APIクライアントがサブスクライブされている(元のリクエストのクライアント・トークンから識別される)使用プランのOCIDに基づいてバックエンドを動的に選択できます。使用プランのOCIDは、 request.usage_plan[id]コンテキスト変数に格納されます。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.usage_plan[id]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "ocid1.usageplan.oc1..aaaaaaaaab______gap"
              ],
              "name": "free-rule",
              "isDefault": true
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://dev.example.com/"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "ocid1.usageplan.oc1..aaaaaaaaay______lcf"
              ],
              "name": "premium-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://api.example.com"
            }
          }
        ]
      }
    }
  ]
}

この例では、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、APIクライアントがサブスクライブされる使用プランによって異なります。次の2つの使用プランが定義されています。

• Free Tier。OCIDはocid1.usageplan.oc1..aaaaaaaaab______gapです。このOCIDがrequest.usage_plan[id]コンテキスト変数の値である場合、リクエストはhttp://dev.example.com/にルーティングされます。リクエストにクライアント・トークンが含まれていなかった場合、Free Tier使用プランもデフォルトとして使用されます。
• Premium Tier。OCIDはocid1.usageplan.oc1..aaaaaaaaay______lcfです。このOCIDがrequest.usage_plan[id]コンテキスト変数の値である場合、リクエストはhttp://api.example.comにルーティングされます

例5: ヘッダー・パラメータによるバックエンドの選択

APIデプロイメントを構成して、元のリクエストのヘッダーで渡されたパラメータに基づいてバックエンドを動的に選択できます。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.headers[Accept]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "application/json"
              ],
              "name": "json-rule",
              "isDefault": true
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "application/xml"
              ],
              "name": "xml-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://xml.example.com"
            }
          }
        ]
      }
    }
  ]
}

この例では、次のように、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、元のリクエストのAcceptヘッダーの値によって異なります。

• Acceptヘッダーがapplication/json形式のレスポンスをリクエストした場合、リクエストはhttp://api.example.comにルーティングされます。
• Acceptヘッダーがapplication/xml形式のレスポンスをリクエストした場合、リクエストはhttp://xml.example.comにルーティングされます。

例6: 認証パラメータによるバックエンドの選択

APIデプロイメントを構成して、認可プロバイダ・ファンクションによって返された、またはJSON Webトークン(JWT)に含まれている認証パラメータ('claim'とも呼ばれる)に基づいてバックエンドを動的に選択できます。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.auth[tenant]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "tenant-cars"
              ],
              "name": "cars-tenant-rule",
              "isDefault": true
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "tenant-trucks"
              ],
              "name": "trucks-tenant-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://trucks-api.example.com"
            }
          }
        ]
      }
    }
  ]
}

この例では、次のように、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、認可プロバイダ・ファンクションによって返されるtenantクレームの値によって異なります。

• request.auth[tenant]コンテキスト変数がtenant-carsに設定されている場合、リクエストはhttp://cars-api.example.comにルーティングされます
• request.auth[tenant]コンテキスト変数がtenant-trucksに設定されている場合、リクエストはhttp://trucks-api.example.comにルーティングされます

例7: 問合せパラメータによるバックエンドの選択

APIデプロイメントを構成して、元のリクエストによって渡された問合せパラメータに基づいてバックエンドを動的に選択できます。

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.query[vehicle-type]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "car"
              ],
              "isDefault": "true",
              "name": "car-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "minivan",
                "truck"
              ],
              "name": "truck-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}

この例では、次のように、APIゲートウェイがリクエストをhttps://<gateway-hostname>/marketing/salesに解決する方法は、元のリクエストによって渡されたvehicle-type問合せパラメータの値によって異なります。

• vehicle-type問合せパラメータの値がcarの場合、リクエストはcars-api.example.comにルーティングされます。
• vehicle-type問合せパラメータの値がtruckまたはminivanの場合、リクエストは処理のためにOCI関数のサーバーレス関数にルーティングされます。
• vehicle-type問合せパラメータ値がcarでもtruckでもminivanでもない場合、リクエストはデフォルトでcars-api.example.comにルーティングされます。