API-Gateway-Backends auf Basis von Anforderungselementen dynamisch auswählen

Erfahren Sie, wie Sie Anforderungen, die an dasselbe API-Gateway gesendet werden, basierend auf Elementen in der Anforderung mit API Gateway an verschiedene Backends weiterleiten.

Eine häufige Anforderung besteht darin, Anforderungen, die an dasselbe API-Gateway gesendet werden, basierend auf Elementen in der Anforderung an verschiedene Backends weiterzuleiten. Beispiel: So leiten Sie Anforderungen an verschiedene Backends weiter:

Der Host und/oder die Domain und/oder Subdomain, an die eine Anforderung gesendet wurde. Beispiel: So leiten Sie eingehende Anforderungen von cars.example.com und trucks.example.com weiter, die an dasselbe API-Gateway an zwei völlig unterschiedliche Backends gesendet wurden.
Der Nutzungsplan, für den der API-Client, der eine Anforderung sendet, abonniert ist. Beispiel: So leiten Sie eingehende Anforderungen entweder an einen Standardhost für API-Clients weiter, die einen Free Tier-Nutzungsplan abonniert haben, oder an einen Hochleistungshost für API-Clients, die den Premium Tier-Nutzungsplan abonniert haben.
Header und Headerwerte in einer Anforderung. Beispiel: So leiten Sie eine Anforderung, die einen Accept-Header mit dem Wert application/xml enthält, an ein entsprechendes Backend weiter, das eine Antwort dieses Inhaltstyps zurückgibt.

Durch die dynamische Auswahl eines Backends können Sie API-Consumern eine einzelne Fassade präsentieren und sie vor der Komplexität mehrerer Backend-Systeme schützen.

Sie können Anforderungen dynamisch an folgende Ziele weiterleiten:

HTTP-Backends
Serverlose Funktions-Backends
Lagerantwort-Backends

Wenn Sie mehrere Backends für dasselbe API-Deployment definieren, erstellen Sie Regeln, damit das API-Gateway basierend auf einem Element in der ursprünglichen Anforderung dynamisch das Backend auswählen kann, an das eine Anforderung weitergeleitet werden soll.

Damit das API-Gateway das richtige Backend dynamisch auswählen kann, verwenden Sie die folgenden Kontextvariablen, um Elemente der Anforderung zu erfassen:

request.auth[<key>], wobei <key> der Name eines Claims ist, der von einer Autorisiererfunktion zurückgegeben oder in einem JWT-Token enthalten ist.
request.headers[<key>], wobei <key> der Name eines Headers ist, der in der Anforderung an die API enthalten ist.
request.host als Name des Hosts, an den die ursprüngliche Anforderung gesendet wurde.
request.path[<key>], wobei <key> der Name eines Pfadparameters ist, der in der API-Deployment-Spezifikation definiert ist.
request.query[<key>], wobei <key> der Name eines Abfrageparameters ist, der in der Anforderung an die API enthalten ist.
request.subdomain[<key>], wobei <key> der nachgestellte Teil des Hostnamens ist, der beim Erfassen des führenden Teils des Hostnamens, an den die ursprüngliche Anforderung gesendet wurde, ignoriert werden soll.
request.usage_plan[id], wobei id die OCID eines Nutzungsplans ist, für den der API-Client abonniert ist.

Wenn eine Kontextvariable mehrere Werte aufweist, wird bei der Auswahl des Backends nur der erste Wert verwendet. Weitere Informationen zu kontextabhängigen Variablen finden Sie unter Kontextabhängige Variablen zu Policys und HTTP-Backend-Definitionen hinzufügen.

Sie definieren die Kriterien zur dynamischen Auswahl von Backends in einer API-Deployment-Spezifikation wie folgt:

die Konsole verwenden
eine JSON-Datei bearbeiten

Hinweise zum Abgleich von Backend-Regeln

Wenn Sie die Regeln erstellen, um zu bestimmen, welches Backend verwendet werden soll, können Sie angeben, wie eng der Kontextvariablenwert mit einem bestimmten Wert übereinstimmen muss, damit die Anforderung an ein bestimmtes Backend weitergeleitet wird. Sie können eine genaue Übereinstimmung oder einen Wert angeben, der mit einem Platzhalter beginnt oder mit diesem endet. Das API-Gateway wertet die Regeln in der von Ihnen angegebenen Reihenfolge aus (genau übereinstimmende Regeln zuerst, gefolgt von Platzhalterregeln) und verwendet die erste Übereinstimmungsregel. Sie können auch eine Standardregel angeben, die verwendet werden soll, wenn der Wert der Kontextvariablen nicht mit Backend-Regeln übereinstimmt. Wenn keine Regel als Standardwert angegeben ist und der Kontextvariablenwert in einer eingehenden Anforderung mit keinen Backend-Regeln übereinstimmt, gibt die Anforderung einen Fehler zurück. Die Prioritätsreihenfolge zur Bestimmung der zu verwendenden Backend-Regel (und damit des zu verwendenden Backends) kann wie folgt zusammengefasst werden:

Wenn der Wert der Kontextvariablen genau mit dem Wert einer Regel übereinstimmt, verwenden Sie diese Regel.
Wenn der Wert der Kontextvariablen mit dem Wert einer Regel übereinstimmt, die mit einem Platzhalter beginnt oder endet, verwenden Sie die erste Regel, die einen übereinstimmenden Platzhalter enthält.
Andernfalls verwenden Sie diese Regel, wenn eine Regel als Standardregel angegeben ist.
Andernfalls geben Sie einen Fehler zurück.

Dynamische Backend-Auswahl mit der Konsole zu einer API-Deployment-Spezifikation hinzufügen

So fügen Sie mit der Konsole eine dynamische Backend-Auswahl zu einer API-Deployment-Spezifikation hinzu:

Erstellen oder aktualisieren Sie ein API-Deployment mit der Konsole, wählen Sie die Option Völlig neu aus, und geben Sie auf der Seite Basisinformationen Details ein.

Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.
Geben Sie auf der Seite Authentifizierung an, wie Anforderungen an Routen im API-Deployment authentifiziert werden sollen.
Weitere Informationen finden Sie unter Authentifizierung und Autorisierung zu API-Deployments hinzufügen.
Erstellen Sie auf der Seite Routen eine neue Route, und geben Sie Folgendes an:
- Pfad: Einen Pfad zum Backend-Service für API-Aufrufe, die die aufgeführten Methoden verwenden. Beachten Sie, dass der von Ihnen angegebene Routenpfad:
  - relativ zum Deployment-Pfadpräfix ist (siehe API durch das Erstellen eines API-Deployments in einem API-Gateway bereitstellen)
  - einen Schrägstrich ( / ) vorangestellt haben muss. Es kann nur ein einzelner Schrägstrich verwendet werden
  - mehrere Schrägstriche enthalten (sofern diese nicht aufeinander folgen) und mit einem Schrägstrich enden kann
  - alphanumerische Zeichen in Großbuchstaben und Kleinbuchstaben enthalten kann
  - die folgenden Sonderzeichen enthalten kann: $ - _ . + ! * ' ( ) , % ; : @ & =
  - Parameter und Platzhalter enthalten kann (siehe Pfadparameter und Platzhalter zu Routenpfaden hinzufügen)
- Methoden: Eine oder mehrere Methoden, die vom Backend-Service akzeptiert werden. Beispiel: GET, PUT.
Wählen Sie Mehrere Backends hinzufügen aus, um anzugeben, dass Anforderungen entsprechend der von Ihnen eingegebenen Kontextvariable und Regeln an verschiedene Backends weitergeleitet werden sollen.
1. Wählen Sie in der Liste Selektor wie folgt die Kontexttabelle (mit der Kontextvariablen), die bei der Bestimmung des Backends verwendet werden soll, an das die Anforderung gesendet werden soll:
  - Auth: Verwenden Sie den Wert eines Claims, der von einer Autorisiererfunktion zurückgegeben oder in einem JWT enthalten ist (und in der Kontexttabelle request.auth gespeichert ist), um das Backend zu bestimmen.
  - Header: Verwenden Sie den Wert eines Headers aus der ursprünglichen Anforderung (und in der Kontexttabelle request.headers gespeichert), um das Backend zu bestimmen.
  - Host: Verwenden Sie den Namen des Hosts, an den die ursprüngliche Anforderung gesendet wurde (aus dem Hostfeld des Hostheaders in der Anforderung extrahiert und in der Kontexttabelle request.host gespeichert), um das Backend zu bestimmen.
  - Pfad: Verwenden Sie einen Pfadparameter aus der ursprünglichen Anforderung (und in der Kontexttabelle request.path gespeichert), um das Backend zu bestimmen.
  - Abfrageparameter: Verwenden Sie den Wert eines Abfrageparameters aus der ursprünglichen Anforderung (und in der Kontexttabelle request.query gespeichert), um das Backend zu bestimmen.
  - Subdomain: Verwenden Sie den führenden Teil des Hostnamens, an den die ursprüngliche Anforderung gesendet wurde (nur diesen Teil des Hostnamens, der nicht als Schlüssel angegeben und in der Kontexttabelle request.subdomain gespeichert ist), um das Backend zu bestimmen. Beachten Sie, dass der Schlüssel der nachgestellte Teil des Hostnamens ist, der nicht verwendet werden soll.
  - Nutzungsplan-OCID: Verwenden Sie die OCID eines Nutzungsplans, für den der API-Client abonniert ist (identifiziert aus einem Clienttoken in der ursprünglichen Anforderung und gespeichert in der Kontexttabelle request.usage_plan), um das Backend zu bestimmen.
2. Geben Sie je nach ausgewählter Kontexttabelle den Namen des Schlüssels ein, der bei der Bestimmung des Backends verwendet werden soll, an das die Anforderung gesendet werden soll.
Wählen Sie Backend definieren aus, um eine Regel für die Kontextvariable einzugeben, die bei Erfüllung die Anforderung an das von Ihnen definierte Backend weiterleitet.
Geben Sie wie folgt Details für die Regel ein:
- Name: Geben Sie einen Namen für die Regel ein. Verwenden Sie den Namen, den Sie eingeben, um das Backend zu identifizieren, wenn Sie auf Logs und Metriken verweisen.
- Übereinstimmungstyp: Geben Sie an, wie eng der Wert der Kontextvariablen mit einem Wert übereinstimmen muss, den Sie eingeben, damit die Anforderung an dieses Backend weitergeleitet wird. Wählen Sie Beliebig von aus, wenn die Kontextvariable genau mit dem Wert im Feld Werte übereinstimmen soll. Wählen Sie Platzhalter, wenn die Kontextvariable mit einem Wert im Feld Ausdruck übereinstimmen muss, der Platzhalter enthält. Bei der Wertübereinstimmung wird die Groß-/Kleinschreibung nicht beachtet, wenn Sie Beliebig von auswählen. Bei der Auswahl von Platzhalter wird die Groß-/Kleinschreibung beachtet.
- Werte: (Wird angezeigt, wenn Sie im Feld Übereinstimmungstyp die Option Beliebig von ausgewählt haben.) Geben Sie einen Wert (oder mehrere Werte in einer durch Komma getrennten Liste) an, mit dem die Kontextvariable genau übereinstimmen muss. Beachten Sie, dass bei der Übereinstimmung die Groß-/Kleinschreibung nicht beachtet wird, wenn Sie Beliebig von ausgewählt haben. Beachten Sie außerdem, dass Werte in einer einzelnen Backend-Regel und in allen für das API-Deployment definierten Backend-Regeln eindeutig sein müssen.
- Ausdruck: (Wird angezeigt, wenn Sie im Feld Übereinstimmungstyp die Option Platzhalter ausgewählt haben) Geben Sie einen Wert an, der mit einem Platzhalter beginnt oder mit diesem endet, mit dem die Kontextvariable übereinstimmen muss. Verwenden Sie den Platzhalter * (Sternchen), um null oder mehr Zeichen anzugeben, und/oder den Platzhalter + (Pluszeichen), um ein oder mehrere Zeichen anzugeben. Beachten Sie, dass bei der Übereinstimmung die Groß-/Kleinschreibung beachtet wird, wenn Sie Platzhalter ausgewählt haben. Beachten Sie, dass Sie nicht mehr als einen Platzhalter in einen Wert aufnehmen können und dass Sie keinen Platzhalter in der Mitte eines Wertes einfügen können. Beachten Sie außerdem, dass eine falsche Platzhalterkonfiguration dazu führen kann, dass Anforderungen an unbeabsichtigte Backends weitergeleitet werden.
- Standardwert festlegen: Geben Sie an, ob das für diese Regel definierte Backend verwendet werden soll, wenn keine Backend-Regeln übereinstimmen.
Geben Sie Details für das Backend wie folgt ein:
1. Wählen Sie im Feld Backend-Typ die Option HTTP/HTTPS, Oracle Functions, Aktienantwort oder Abmeldung als Backend aus, an das die Anforderung weitergeleitet werden soll, wenn die eingegebene Regel erfüllt ist.
2. Geben Sie Details für das ausgewählte Backend ein. Die einzugebenden Details hängen vom ausgewählten Backend-Typ ab und werden vollständig in den folgenden Abschnitten beschrieben:
3. Wählen Sie Definieren aus, um das Backend und die zugehörige Regel zu erstellen.
(Optional) Wählen Sie erneut Backend definieren aus, um zusätzliche Backends und zugehörige Regeln zu definieren.
(Optional) Wählen Sie Weitere Route aus, um Details zusätzlicher Routen einzugeben.
Wählen Sie Weiter aus, um die Details zu prüfen, die Sie für das API-Deployment eingegeben haben.
Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
(Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

JSON-Datei bearbeiten, um einer API-Deployment-Spezifikation eine dynamische Backend-Auswahl hinzuzufügen

So fügen Sie eine dynamische Backend-Auswahl zu einer API-Deployment-Spezifikation in einer JSON-Datei hinzu:

Erstellen Sie mit Ihrem bevorzugten JSON-Editor eine neue API-Deployment-Spezifikation (siehe API-Deployment-Spezifikation erstellen) in folgendem Format:
```
{
  "requestPolicies": {},
  "routes": [
    {
      "path": "<api-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "<context-table-key>"
        },
        "routingBackends": [
          {
            "key": {
              "type": "<ANY_OF|WILDCARD>",
              "values": [
                "<context-variable-value>"
              ],
              "isDefault": "<true|false>",
              "name": "<rule-name>"
            },
            "backend": {
              "type": "<backend-type>",
              "<backend-target>": "<identifier>"
            }
          }
        ]
      }
    }
  ]
}
```
Dabei gilt:
- "requestPolicies" gibt optionale Policys an, mit denen das Verhalten eines API-Deployments gesteuert wird. Wenn Sie Policys auf alle Routen in einer API-Deployment-Spezifikation anwenden möchten, platzieren Sie die Policys außerhalb des routes-Abschnitts. Wenn Sie Policys nur auf eine bestimmte Route anwenden möchten, platzieren Sie die Policys innerhalb des routes-Abschnitts. Siehe Anforderungs-Policys und Antwort-Policys zu API-Deployment-Spezifikationen hinzufügen.
- <api-route-path> gibt einen Pfad zum Backend-Service für API-Aufrufe an, die die aufgeführten Methoden verwenden. Beachten Sie, dass der von Ihnen angegebene Routenpfad:
  - relativ zum Deployment-Pfadpräfix ist (siehe API durch das Erstellen eines API-Deployments in einem API-Gateway bereitstellen)
  - einen Schrägstrich ( / ) vorangestellt haben muss. Es kann nur ein einzelner Schrägstrich verwendet werden
  - mehrere Schrägstriche enthalten (sofern diese nicht aufeinander folgen) und mit einem Schrägstrich enden kann
  - alphanumerische Zeichen in Großbuchstaben und Kleinbuchstaben enthalten kann
  - die folgenden Sonderzeichen enthalten kann: $ - _ . + ! * ' ( ) , % ; : @ & =
  - Parameter und Platzhalter enthalten kann (siehe Pfadparameter und Platzhalter zu Routenpfaden hinzufügen)
- <method-list> gibt eine oder mehrere Methoden, die vom Backend-Service akzeptiert werden, durch Komma getrennt an. Beispiel: "GET, PUT".
- "type": "DYNAMIC_ROUTING_BACKEND" gibt an, dass Sie das Backend basierend auf Elementen in der Anforderung dynamisch auswählen möchten.
- "type": "SINGLE" gibt an, dass Sie eine einzelne Kontextvariable zur dynamischen Auswahl des Backends verwenden möchten.
- "selector": "<context-table-key>" gibt die Kontexttabelle (und gegebenenfalls den Schlüssel) an, aus der der Kontextvariablenwert abgerufen werden soll, der das Backend bestimmt, an das die Anforderung gesendet werden soll, wie folgt:
  - request.auth[<key>] Verwenden Sie den Wert eines Claims, der von einer Autorisiererfunktion zurückgegeben wird oder in einem JSON Web Token (JWT) enthalten ist, um das Backend zu bestimmen. <key> ist der Name des Claims. Beispiel: request.auth[tenant]
  - request.headers[<key>] Verwenden Sie den Wert eines Headers aus der ursprünglichen Anforderung, um das Backend zu bestimmen. <key> ist der Headername. Beispiel: request.headers[Accept]
  - request.host Verwenden Sie den Namen des Hosts, an den die ursprüngliche Anforderung gesendet wurde (aus dem Hostfeld des Hostheaders in der Anforderung extrahiert), um das Backend zu bestimmen.
  - request.path[<key>] Verwenden Sie einen Pfadparameter aus der ursprünglichen Anforderung, um das Backend zu bestimmen. <key> ist der Pfadparametername. Beispiel: request.path[region]
  - request.query[<key>] Verwenden Sie den Wert eines Abfrageparameters aus der ursprünglichen Anforderung, um das Backend zu bestimmen. <key> ist der Abfrageparametername. Beispiel: request.query[state]
  - request.subdomain[<key>] Verwenden Sie den führenden Teil des Hostnamens, an den die ursprüngliche Anforderung gesendet wurde (nur den Teil des Hostnamens, der nicht als Schlüssel angegeben ist), um das Backend zu bestimmen. Beachten Sie, dass <key> der nachgestellte Teil des Hostnamens ist, der nicht verwendet werden soll. Beispiel: request.subdomain[example.com]
  - request.usage_plan[id] Verwenden Sie die OCID eines Nutzungsplans, für den der API-Client abonniert ist (in der ursprünglichen Anforderung aus einem Clienttoken identifiziert), um das Backend zu bestimmen.
- "key": {...} gibt die Regel an, die erfüllt werden muss, um eine Anforderung an das durch "backend": {…} angegebene Backend zu senden.
- "type": "<ANY_OF|WILDCARD>" gibt an, wie eng der Wert der mit <context-table-key> identifizierten Kontextvariablen mit dem Wert übereinstimmen muss, den Sie für <context-variable-value> eingeben, damit die Anforderung an das mit "backend": {…} angegebene Backend gesendet wird. Geben Sie ANY_OF an, wenn der Wert der mit <context-table-key> identifizierten Kontextvariablen genau mit dem Wert übereinstimmen muss, den Sie für <context-variable-value> angeben. Geben Sie WILDCARD an, wenn der Wert der mit <context-table-key> identifizierten Kontextvariablen mit einem Wert übereinstimmen muss, der Platzhalter enthält, die Sie für <context-variable-value> angeben. Bei der Wertübereinstimmung wird die Groß-/Kleinschreibung nicht beachtet, wenn Sie ANY_OF angeben. Wenn Sie WILDCARD angeben, wird die Groß-/Kleinschreibung beachtet.
- <context-variable-value> ist ein Wert, der möglicherweise mit dem Wert der mit <context-table-key> identifizierten Kontextvariable übereinstimmt. Sie können mehrere "<context-variable-value>"-Einträge in das Array values:[...] aufnehmen, getrennt durch Kommas. Die Anforderung wird wie folgt an das von "backend": {…} angegebene Backend gesendet, wenn die Werte übereinstimmen:
  - Wenn Sie "type": "ANY_OF" angegeben haben, müssen die Werte genau übereinstimmen. Beachten Sie, dass Werte innerhalb einer einzelnen Backend-Regel und in allen Backend-Regeln, die für ein API-Deployment definiert sind, eindeutig sein müssen. Bei der Wertübereinstimmung wird die Groß-/Kleinschreibung nicht beachtet, wenn Sie ANY_OF angegeben haben.
  - Wenn Sie "type": "WILDCARD" angegeben haben, können Sie einen Wert für <context-variable-value> angeben, der mit einem Platzhalter beginnt oder mit diesem endet. Verwenden Sie den Platzhalter * (Sternchen), um null oder mehr Zeichen anzugeben, und/oder den Platzhalter + (Pluszeichen), um ein oder mehrere Zeichen anzugeben. Beachten Sie, dass Sie nicht mehr als einen Platzhalter in einen Wert aufnehmen können und dass Sie keinen Platzhalter in der Mitte eines Wertes einfügen können. Bei der Wertübereinstimmung wird die Groß-/Kleinschreibung beachtet, wenn Sie WILDCARD angegeben haben. Beachten Sie außerdem, dass eine falsche Platzhalterkonfiguration dazu führen kann, dass Anforderungen an unbeabsichtigte Backends weitergeleitet werden.
  Beispiel: Wenn eine Anforderung von einem API-Client, der eine xml-Antwort akzeptieren kann (wie im Accept-Header der Anforderung angegeben), an ein Backend weitergeleitet werden soll, das xml zurückgibt, können Sie Folgendes angeben:
  - "selector": "request.headers[Accept]"
  - "type": "ANY_OF"
  - "values": ["application/xml"]
- "isDefault": "<true|false>" ist ein optionaler boolescher Wert (entweder true oder false), der angibt, ob das Backend für diese Regel verwendet werden soll, wenn keine Backend-Regeln übereinstimmen. Wenn kein Wert angegeben wurde, wird standardmäßig false verwendet.
- "name": "<rule-name>" gibt einen Namen für die Regel an. Verwenden Sie diesen Namen, um das Backend beim Verweisen auf Logs und Metriken zu identifizieren.
- <backend-type> gibt den Typ des Backend-Service an. Gültige Werte sind ORACLE_FUNCTIONS_BACKEND, HTTP_BACKEND und STOCK_RESPONSE_BACKEND.
- <backend-target> und <identifier> geben den Backend-Service an. Gültige Werte für <backend-target> und <identifier> hängen wie folgt vom Wert für <backend-type> ab:
  - Wenn Sie <backend-type> auf ORACLE_FUNCTIONS_BACKEND setzen, dann ersetzen Sie <backend-target> durch functionId und <identifier> durch die OCID der Funktion. Beispiel: "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab5b...". Siehe Funktion in OCI Functions als API-Gateway-Backend hinzufügen.
  - Wenn Sie <backend-type> auf HTTP_BACKEND setzen, dann ersetzen Sie <backend-target> durch url, und <identifier> durch die URL des Backend-Service. Beispiel: "url": "https://api.weather.gov". Siehe HTTP- oder HTTPS-URL als API-Gateway-Backend hinzufügen.
  - Wenn Sie <backend-type> auf STOCK_RESPONSE_BACKEND setzen, dann ersetzen Sie <backend-target> und <identifier> durch entsprechende Schlüsselwertpaare. Siehe Standardantworten als API-Gateway-Backend hinzufügen.
Beispiel: Die folgende allgemeine API-Deployment-Spezifikation enthält eine dynamische Backend-Auswahl, die Anforderungen basierend auf dem Wert des Abfrageparameters vehicle-type weiterleitet, der in der Anforderung übergeben wurde. Wenn der Abfrageparameter vehicle-type den Wert car aufweist, wird die Anforderung an cars-api.example.com weitergeleitet. Wenn der Abfrageparameter vehicle-type den Wert truck oder minivan aufweist, wird die Anforderung zur Verarbeitung an eine serverlose Funktion in OCI Functions weitergeleitet. Wenn der Abfrageparameterwert vehicle-type weder car noch truck noch minivan ist, wird die Anforderung standardmäßig an cars-api.example.com weitergeleitet:
```
{
  "routes": [
    {
      "path": "/users/{path1*}",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.query[vehicle-type]"
        },
        "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": [
                "minivan",
                "truck"
              ],
              "name": "truck-minivan-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}
```
Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.
Verwenden Sie die API-Deployment-Spezifikation, wenn Sie ein API-Deployment wie folgt erstellen oder aktualisieren:
- Durch Angabe der JSON-Datei in der Konsole bei Auswahl der Option Vorhandene API hochladen
- Durch Angabe der JSON-Datei in einer Anforderung an die REST-API von API-Gateway
Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployments in einem API-Gateway bereitstellen.
(Optional) Bestätigen Sie, dass die API bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

Beispiele für die dynamische Auswahl von API-Gateway-Backends

In den Beispielen in diesem Abschnitt wird von der folgenden API-Deployment-Definition und unvollständigen API-Deployment-Spezifikation in einer JSON-Datei ausgegangen:

{
  "displayName": "Marketing Deployment",
  "gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
  "pathPrefix": "/marketing",
  "specification": {
    "routes": [
      {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        .
        .
        .
        }
      }
    ]
  },
  "freeformTags": {},
  "definedTags": {}
}

Beachten Sie, dass diese Beispiele auch gelten, wenn Sie eine API-Deployment-Spezifikation mit Dialogfeldern in der Konsole definieren.

Beispiel 1: Backend nach Host auswählen

Sie können ein API-Deployment so konfigurieren, dass ein Backend basierend auf dem Host, an den die ursprüngliche Anforderung gesendet wurde (aus dem Hostfeld des Hostheaders in der Anforderung extrahiert) dynamisch ausgewählt wird. Mit diesem Design können Sie ein API-Gateway definieren, das verschiedene Mandanten unterstützt.

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

In diesem Beispiel hängt die Art und Weise, wie das API-Gateway eine Anforderung in https://<gateway-hostname>/marketing/sales auflöst, wie folgt vom Host ab, an den die ursprüngliche Anforderung gesendet wurde (aus dem Hostfeld des Hostheaders in der Anforderung extrahiert):

Wenn die Anforderung an cars.example.com gesendet wurde, wird sie an http://cars-api.example.com weitergeleitet.
Wenn die Anforderung an minivans.examplecloud.com oder trucks.example.com gesendet wurde, wird die Anforderung an ein serverloses Funktions-Backend in OCI Functions weitergeleitet.
Wenn die Anforderung an einen anderen Host gesendet wurde, wird die Anforderung standardmäßig an http://cars-api.example.com weitergeleitet.

Beispiel 2: Backend nach Hostsubdomain auswählen

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

In diesem Beispiel hängt die Art und Weise, wie das API-Gateway eine Anforderung an https://<gateway-hostname>/marketing/sales auflöst, wie folgt von der Hostsubdomain ab, an die die ursprüngliche Anforderung gesendet wurde:

Wenn die Anforderung an cars.example.com gesendet wurde, wird die Anforderung an http://cars-api.example.com weitergeleitet
Wenn die Anforderung an minivans.example.com oder trucks.example.com gesendet wurde, wird die Anforderung an ein serverloses Funktions-Backend in OCI Functions weitergeleitet
Wenn die Anforderung an eine andere Subdomain von example.com gesendet wurde (wie car.example.com oder sedan.example.com), wird die Anforderung standardmäßig an http://cars-api.example.com weitergeleitet.

Beispiel 3a: Wählen Sie das Backend nach Hostsubdomain aus (ändern Sie den Hostnamen in der Backend-URL, und verwenden Sie den Abgleichstyp ANY_OF)

Sie können ein API-Deployment so konfigurieren, dass ein Backend basierend auf einer Subdomain in der Hostzeichenfolge, an die die ursprüngliche Anforderung gesendet wurde, dynamisch ausgewählt wird. Die Hostzeichenfolge wird aus dem Hostheader in der Anforderung extrahiert und durch eine von Ihnen angegebene Zeichenfolge maskiert. Dabei bleibt die Subdomain übrig, die zum Weiterleiten der Anforderung verwendet wird. Zur zusätzlichen Validierung können Sie die Subdomainmaske als Kontextvariable in die Backend-URL aufnehmen, um sicherzustellen, dass Anforderungen nur an Backends weitergeleitet werden, die Sie bereitstellen möchten. Wenn Sie ANY_OF als Abgleichstyp angeben, darf der Wert der Kontextvariable keine Platzhalter enthalten und muss genau mit einem der routes.routingBackends.key-Werte übereinstimmen, damit die Anforderung an das Backend gesendet wird.

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

Wenn die Anforderung an cars.example.com oder hatchbacks.example.com gesendet wurde, wird die Anforderung an http://cars-api.example.com oder http://hatchbacks-api.example.com weitergeleitet
Wenn die Anforderung an eine andere Subdomain von example.com gesendet wurde (wie suvs.example.com oder sedans.example.com), verläuft die Anforderung nicht erfolgreich.

Wenn Sie erwägen, den Hostnamen in der Backend-URL durch Aufnahme einer Kontextvariablen zu ändern, wie in diesem Beispiel dargestellt, beachten Sie Folgendes:

Sie können die Backend-URL nur mit der für selector angegebenen Kontextvariablen ändern.
Um die Liste der zulässigen Backends durchzusetzen, legen Sie "isDefault: "true" für keine Regel fest.

Beispiel 3b: Wählen Sie das Backend nach Hostsubdomain aus (ändern Sie den Hostnamen in der Backend-URL, und verwenden Sie den Abgleichstyp WILDCARD)

Sie können ein API-Deployment so konfigurieren, dass ein Backend basierend auf einer Subdomain in der Hostzeichenfolge, an die die ursprüngliche Anforderung gesendet wurde, dynamisch ausgewählt wird. Die Hostzeichenfolge wird aus dem Hostheader in der Anforderung extrahiert und durch eine von Ihnen angegebene Zeichenfolge maskiert. Dabei bleibt die Subdomain übrig, die zum Weiterleiten der Anforderung verwendet wird. Zur zusätzlichen Validierung können Sie die Subdomainmaske als Kontextvariable in die Backend-URL aufnehmen, um sicherzustellen, dass Anforderungen nur an Backends weitergeleitet werden, die Sie bereitstellen möchten. Wenn Sie WILDCARD als Abgleichstyp angeben, kann der Wert der Kontextvariable Platzhalter enthalten und muss mit einem der routes.routingBackends.key-Werte übereinstimmen, damit die Anforderung an das Backend gesendet wird.

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

In diesem Beispiel hängt die Art und Weise, wie das API-Gateway eine Anforderung in https://<gateway-hostname>/marketing/sales auflöst, davon ab, ob die Hostsubdomain, an die die ursprüngliche Anforderung gesendet wurde, mit dem Wert routes.routingBackends.key einschließlich des Platzhalters übereinstimmt. In diesem Fall wie folgt, ob die ursprüngliche Anforderung an eine Hostsubdomain gesendet wurde, die mit dem Buchstaben "s" endet:

Wenn die Anforderung an eine Subdomain gesendet wurde, die mit dem Buchstaben "s" endet, wird die Anforderung entsprechend weitergeleitet. Beispiel: Anforderungen, die an cars.example.com, hatchbacks.example.com, suvs.example.com oder sedans.example.com gesendet werden, werden an http://cars-api.example.com, http://hatchbacks-api.example.com, http://suvs-api.example.com bzw. http://sedans-api.example.com weitergeleitet.
Wenn die Anforderung an eine Subdomain gesendet wurde, die nicht mit dem Buchstaben 's' endet, schlägt die Anforderung fehl. Beispiel: Anforderungen, die an truck.example.com oder tractor.example.com gesendet wurden, sind nicht erfolgreich.

Wenn Sie erwägen, den Hostnamen in der Backend-URL zu ändern, indem Sie eine Kontextvariable einschließen, wie in diesem Beispiel dargestellt:

Sie können die Backend-URL nur mit der für selector angegebenen Kontextvariable ändern.
Wenn Sie Platzhalter verwenden, konfigurieren Sie den Platzhalter sorgfältig. Eine falsche Platzhalterkonfiguration kann dazu führen, dass Anforderungen an unbeabsichtigte Backends weitergeleitet werden. Beispiel: Im Beispiel werden Anforderungen, die an buses.example.com gesendet wurden, wie erwartet korrekt an http://buses-api.example.com weitergeleitet. Diese Konfiguration leitet jedoch auch Anforderungen weiter, die ursprünglich an bus.example.com bzw. s.example.com gesendet wurden, an http://bus-api.example.com bzw. http://s-api.example.com, von denen keiner beabsichtigt war.

Beispiel 4: Backend nach Nutzungsplan auswählen

Sie können ein API-Deployment so konfigurieren, dass basierend auf der OCID eines Nutzungsplans, für den der API-Client abonniert ist (in der ursprünglichen Anforderung aus einem Clienttoken identifiziert), dynamisch ein Backend ausgewählt wird. Die OCID des Nutzungsplans wird in der Kontextvariable request.usage_plan[id] gespeichert.

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

In diesem Beispiel hängt die Art und Weise, wie das API-Gateway eine Anforderung an https://<gateway-hostname>/marketing/sales auflöst, vom Nutzungsplan ab, für den der API-Client abonniert ist. Es wurden zwei Nutzungspläne wie folgt definiert:

Free Tier mit der OCID ocid1.usageplan.oc1..aaaaaaaaab______gap. Wenn diese OCID der Wert der Kontextvariablen request.usage_plan[id] ist, wird die Anforderung an http://dev.example.com/ weitergeleitet. Der Nutzungsplan Free Tier wird auch als Standard verwendet, wenn die Anforderung kein Clienttoken enthielt.
Premium Tier mit der OCID ocid1.usageplan.oc1..aaaaaaaaay______lcf. Wenn diese OCID der Wert der Kontextvariablen request.usage_plan[id] ist, wird die Anforderung an http://api.example.com weitergeleitet.

Beispiel 5: Backend nach Headerparameter auswählen

Sie können ein API-Deployment so konfigurieren, dass ein Backend basierend auf einem Parameter, der im Header der ursprünglichen Anforderung übergeben wird, dynamisch ausgewählt wird.

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

In diesem Beispiel hängt die Auflösung einer Anforderung durch das API-Gateway in https://<gateway-hostname>/marketing/sales wie folgt vom Wert des Accept-Headers in der ursprünglichen Anforderung ab:

Wenn der Accept-Header eine Antwort im Format application/json anfordert, wird die Anforderung an http://api.example.com weitergeleitet
Wenn der Accept-Header eine Antwort im Format application/xml anfordert, wird die Anforderung an http://xml.example.com weitergeleitet

Beispiel 6: Backend durch Authentifizierungsparameter auswählen

Sie können ein API-Deployment so konfigurieren, dass ein Backend basierend auf einem Authentifizierungsparameter (auch als "Anspruch" bezeichnet) dynamisch ausgewählt wird, der von einer Autorisiererfunktion zurückgegeben wird oder in einem JSON Web Token (JWT) enthalten ist.

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

In diesem Beispiel hängt die Auflösung einer Anforderung durch das API-Gateway in https://<gateway-hostname>/marketing/sales wie folgt vom Wert des tenant-Claims ab, der von einer Autorisiererfunktion zurückgegeben wird:

Wenn die Kontextvariable request.auth[tenant] auf tenant-cars gesetzt ist, wird die Anforderung an http://cars-api.example.com weitergeleitet.
Wenn die Kontextvariable request.auth[tenant] auf tenant-trucks gesetzt ist, wird die Anforderung an http://trucks-api.example.com weitergeleitet.

Beispiel 7: Backend durch Abfrageparameter auswählen

Sie können ein API-Deployment so konfigurieren, dass basierend auf einem Abfrageparameter, der von der ursprünglichen Anforderung übergeben wird, dynamisch ein Backend ausgewählt wird.

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

In diesem Beispiel hängt die Auflösung einer Anforderung durch das API-Gateway in https://<gateway-hostname>/marketing/sales vom Wert des Abfrageparameters vehicle-type ab, der von der ursprünglichen Anforderung übergeben wird. Gehen Sie dazu wie folgt vor:

Wenn der Abfrageparameter vehicle-type den Wert car aufweist, wird die Anforderung an cars-api.example.com weitergeleitet.
Wenn der Abfrageparameter vehicle-type den Wert truck oder minivan aufweist, wird die Anforderung zur Verarbeitung an eine serverlose Funktion in OCI Functions weitergeleitet.
Wenn der Abfrageparameterwert vehicle-type weder car noch truck oder minivan lautet, wird die Anforderung standardmäßig an cars-api.example.com weitergeleitet:

Oracle Cloud Infrastructure - Dokumentation