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

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

You can configure an API deployment to dynamically select a back end based on the host to which the original request was sent (extracted from the host field of the Host header in the request). This design enables you to define an API gateway that supports different tenants.

{
  "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",
              "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"
            }
          }
        ]
      }
    }
  ]
}

In this example, how the API gateway resolves a request to https://<gateway-hostname>/marketing/sales depends on the host to which the original request was sent (extracted from the host field of the Host header in the request), as follows:

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

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

You can configure an API deployment to dynamically select a back end based on a subdomain in the host string to which the original request was sent.ホスト文字列は、リクエストのホスト・ヘッダーから抽出され、指定した文字列でマスクされ、リクエストのルーティングに使用されるサブドメインが残ります。This design enables you to define an API gateway that supports different tenants.

{
  "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",
              "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"
            }
          }
        ]
      }
    }
  ]
}

In this example, how the API gateway resolves a request to https://<gateway-hostname>/marketing/sales depends on the host subdomain to which the original request was sent, as follows:

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

Example 3: Select back end by Host Subdomain (modifying the host name in the back end URL)

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

{
  "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",
              "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"を設定しないでください。

例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",
              "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 Functionsのサーバーレス・ファンクションにルーティングされます。
• vehicle-type問合せパラメータ値がcarでもtruckでもminivanでもない場合、リクエストはデフォルトでcars-api.example.comにルーティングされます。