Selezione dinamica dei backend del gateway API in base agli elementi di richiesta

Scopri come instradare le richieste inviate allo stesso gateway API a backend diversi in base agli elementi della richiesta con API Gateway.

Un requisito comune è quello di instradare le richieste inviate allo stesso gateway API a backend diversi in base agli elementi nella richiesta. Ad esempio, per instradare le richieste a backend diversi in base a:

L'host e/o il dominio e/o il sottodominio a cui è stata inviata una richiesta. Ad esempio, per instradare le richieste in entrata da cars.example.com e trucks.example.com inviate allo stesso gateway API a due backend completamente diversi.
Il piano di utilizzo al quale il client API che invia una richiesta è sottoscritto. Ad esempio, per instradare le richieste in entrata a un host standard per i client API sottoscritti a un piano di utilizzo Free Tier o a un host ad alte prestazioni per i client API sottoscritti al piano di utilizzo Premium Tier.
Intestazioni e valori di intestazione in una richiesta. Ad esempio, per instradare una richiesta che include un'intestazione Accept con il valore application/xml a un backend appropriato che restituisce una risposta di quel tipo di contenuto.

La selezione dinamica di un back-end consente di presentare una singola facciata ai consumatori di API e di proteggerli dalla complessità di più sistemi backend.

È possibile instradare dinamicamente le richieste a:

Back-end HTTP
back-end della funzione serverless
back-end risposta stock

Quando si definiscono più backend per la stessa distribuzione API, è possibile creare regole per consentire al gateway API di selezionare in modo dinamico il backend in cui instradare una richiesta, in base a un elemento della richiesta originale.

Per consentire al gateway API di selezionare dinamicamente il backend corretto, utilizzare le variabili di contesto riportate di seguito per acquisire gli elementi della richiesta.

request.auth[<key>] dove <key> è il nome di una richiesta restituita da una funzione del responsabile autorizzazioni o contenuta in un token JWT.
request.headers[<key>] dove <key> è il nome di un'intestazione inclusa nella richiesta all'API.
request.host come nome dell'host a cui è stata inviata la richiesta originale.
request.path[<key>] dove <key> è il nome di un parametro di percorso definito nella specifica di distribuzione API.
request.query[<key>] dove <key> è il nome di un parametro di query incluso nella richiesta all'API.
request.subdomain[<key>] dove <key> è la parte finale del nome host da ignorare durante l'acquisizione della parte iniziale del nome host a cui è stata inviata la richiesta originale.
request.usage_plan[id] dove id è l'OCID di un piano di utilizzo al quale è stata eseguita la sottoscrizione del client API.

Tenere presente che se una variabile di contesto ha più valori, quando si seleziona il backend viene utilizzato solo il primo valore. Per ulteriori informazioni sulle variabili di contesto, vedere Aggiunta di variabili di contesto ai criteri e alle definizioni backend HTTP.

Puoi definire i criteri per selezionare dinamicamente i back-end in una specifica di distribuzione API in base a:

utilizzo di Console
modifica di un file JSON

Note sulla corrispondenza delle regole backend

Quando si creano le regole per determinare quale backend utilizzare, è possibile specificare la corrispondenza del valore della variabile di contesto con un determinato valore affinché la richiesta venga instradata a un determinato backend. È possibile richiedere una corrispondenza esatta oppure specificare un valore che inizia con o termina con un carattere jolly. Il gateway API valuta le regole nell'ordine specificato (prima le regole di corrispondenza esatta, seguite dalle regole con caratteri jolly) e utilizza la prima regola di corrispondenza. È inoltre possibile specificare una regola predefinita da utilizzare se il valore della variabile di contesto non corrisponde ad alcuna regola backend. Se non viene specificata alcuna regola come predefinita e il valore della variabile di contesto in una richiesta in entrata non corrisponde ad alcuna regola backend, la richiesta restituirà un errore. L'ordine di precedenza per determinare quale regola backend (e quindi quale backend) utilizzare può essere riepilogato come:

Se il valore della variabile di contesto corrisponde esattamente al valore di una regola, utilizzare tale regola.
In caso contrario, se il valore della variabile di contesto corrisponde al valore di una regola che inizia o termina con un carattere jolly, utilizzare la prima regola contenente un carattere jolly corrispondente.
Altrimenti, se una regola è specificata come regola predefinita, utilizzarla.
Altrimenti, restituire un errore.

Utilizzo della console per aggiungere la selezione backend dinamica a una specifica di distribuzione API

Per aggiungere la selezione backend dinamica a una specifica di distribuzione API utilizzando la console:

Creare o aggiornare una distribuzione API utilizzando la console, selezionare l'opzione Da zero e immettere i dettagli nella pagina Informazioni di base.

Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.
Nella pagina Autenticazione specificare come autenticare le richieste effettuate agli instradamenti nella distribuzione dell'API.
Per ulteriori informazioni, vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.
Nella pagina Cicli creare un nuovo instradamento e specificare:
- Percorso: un percorso per le chiamate API che utilizzano i metodi elencati per il servizio backend. Tenere presente che il percorso di instradamento specificato è il seguente:
  - è relativo al prefisso del percorso di distribuzione (vedere Distribuzione di un'API in un gateway API mediante la creazione di una distribuzione API)
  - deve essere preceduta da una barra ( / ) e può essere solo la singola barra
  - può contenere più barre in avanti (a condizione che non siano adiacenti) e può terminare con una barra in avanti
  - può includere caratteri alfanumerici maiuscoli e minuscoli
  - può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
  - può includere parametri e caratteri jolly (vedere Aggiunta di parametri di percorso e caratteri jolly ai percorsi di instradamento)
- Metodi: uno o più metodi accettati dal servizio backend. Ad esempio, GET, PUT.
Selezionare Aggiungi più backend per specificare che si desidera che le richieste vengano instradate a backend diversi, in base alla variabile di contesto e alle regole immesse.
1. Nell'elenco Selettore selezionare la tabella di contesto (contenente la variabile di contesto) da utilizzare per determinare il backend al quale inviare la richiesta, come indicato di seguito.
  - Autore: utilizzare il valore di un risarcimento restituito da una funzione del responsabile autorizzazioni o contenuto in un JWT (e salvato nella tabella di contesto request.auth) per determinare il backend.
  - Intestazioni: utilizzare il valore di un'intestazione della richiesta originale (e salvata nella tabella di contesto request.headers) per determinare il backend.
  - Host: utilizzare il nome dell'host al quale è stata inviata la richiesta originale (estratto dal campo host dell'intestazione dell'host nella richiesta e salvato nella tabella di contesto request.host) per determinare il backend.
  - Percorso: utilizzare un parametro di percorso della richiesta originale (e salvato nella tabella di contesto request.path) per determinare il backend.
  - Parametri query: utilizzare il valore di un parametro di query della richiesta originale (e salvato nella tabella di contesto request.query) per determinare il backend.
  - Dominio secondario: utilizzare la parte iniziale del nome host a cui è stata inviata la richiesta originale, ovvero la parte del nome host non specificata come chiave e salvata nella tabella di contesto request.subdomain, per determinare il backend. Si noti che la chiave è la parte finale del nome host da non utilizzare.
  - OCID piano di utilizzo: utilizzare l'OCID di un piano di utilizzo al quale il client API è stato sottoscritto (identificato da un token client nella richiesta originale e salvato nella tabella di contesto request.usage_plan) per determinare il backend.
2. A seconda della tabella di contesto selezionata, immettere il nome della chiave da utilizzare per determinare il backend a cui inviare la richiesta.
Fare clic su Definisci backend per immettere una regola per la variabile di contesto che, se soddisfatta, instrada la richiesta al backend definito.
Immettere i dettagli per la regola come indicato di seguito.
- Nome: Immettere un nome per la regola. Utilizzare il nome immesso per identificare il backend quando si fa riferimento a log e metriche.
- Tipo di corrispondenza: specificare la precisione con cui il valore della variabile di contesto deve corrispondere a un valore immesso affinché la richiesta venga instradata a questo backend. Selezionare Qualsiasi di se si desidera che la variabile di contesto corrisponda esattamente al valore nel campo Valori. Selezionare Carattere jolly se la variabile di contesto deve corrispondere a un valore nel campo Espressione contenente i caratteri jolly. La corrispondenza dei valori non fa distinzione tra maiuscole e minuscole se si seleziona Qualsiasi di e la distinzione tra maiuscole e minuscole se si seleziona Carattere jolly.
- Valori: (visualizzato se nel campo Tipo di corrispondenza è stata selezionata l'opzione Qualsiasi di). Specificare un valore (o più valori in una lista separata da virgole) che la variabile di contesto deve corrispondere esattamente. Tenere presente che la corrispondenza non fa distinzione tra maiuscole e minuscole se è stata selezionata l'opzione Qualsiasi di. Tenere inoltre presente che i valori devono essere univoci all'interno di una singola regola backend e in tutte le regole backend definite per la distribuzione dell'API.
- Espressione: (visualizzato se è stato selezionato Carattere jolly nel campo Tipo di corrispondenza) specificare un valore che inizia o termina con un carattere jolly a cui deve corrispondere la variabile di contesto. Utilizzare il carattere jolly * (asterisco) per indicare zero o più caratteri e/o il carattere jolly + (segno più) per indicare uno o più caratteri. Tenere presente che la corrispondenza fa distinzione tra maiuscole e minuscole se si seleziona Carattere jolly. Tenere presente che non è possibile includere più di un carattere jolly in un valore e che non è possibile includere un carattere jolly al centro di un valore.
- Impostare l'impostazione predefinita: specificare se utilizzare il backend definito per questa regola se nessuna regola backend corrisponde.
Immettere i dettagli per il backend come indicato di seguito.
1. Nel campo Tipo backend, selezionare HTTP/HTTPS, Oracle Functions, Risposta stock o Logout come back-end per l'instradamento della richiesta se la regola immessa viene soddisfatta.
2. Immettere i dettagli per il backend selezionato. I dettagli da immettere dipendono dal tipo di backend selezionato e sono descritti in modo completo in:
3. Fare clic su Definisci per creare il backend e la regola associata.
(Facoltativo) Fare di nuovo clic su Definisci backend per definire i backend aggiuntivi e le regole associate.
(Facoltativo) Fare clic su Altro instradamento per immettere i dettagli degli instradamenti aggiuntivi.
Fare clic su Successivo per esaminare i dettagli immessi per la distribuzione API.
Fare clic su Crea o su Salva modifiche per creare o aggiornare la distribuzione API.
(Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Modifica di un file JSON per aggiungere la selezione backend dinamica a una specifica di distribuzione API

Per aggiungere la selezione backend dinamica a una specifica di distribuzione API in un file JSON, procedere come segue.

Utilizzando l'editor JSON preferito, creare una nuova specifica di distribuzione API (vedere Creazione di una specifica di distribuzione API) nel formato seguente:
```
{
  "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>"
            }
          }
        ]
      }
    }
  ]
}
```
dove:
- "requestPolicies" specifica i criteri facoltativi per controllare il funzionamento di una distribuzione API. Se si desidera applicare i criteri a tutti gli instradamenti in una specifica di distribuzione API, posizionarli all'esterno della sezione routes. Se si desidera applicare i criteri solo a un instradamento specifico, inserire i criteri nella sezione routes. Vedere Aggiunta di criteri di richiesta e di risposta alle specifiche di distribuzione API.
- <api-route-path> specifica un percorso per le chiamate API utilizzando i metodi elencati per il servizio backend. Tenere presente che il percorso di instradamento specificato è il seguente:
  - è relativo al prefisso del percorso di distribuzione (vedere Distribuzione di un'API in un gateway API mediante la creazione di una distribuzione API)
  - deve essere preceduta da una barra ( / ) e può essere solo la singola barra
  - può contenere più barre in avanti (a condizione che non siano adiacenti) e può terminare con una barra in avanti
  - può includere caratteri alfanumerici maiuscoli e minuscoli
  - può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
  - può includere parametri e caratteri jolly (vedere Aggiunta di parametri di percorso e caratteri jolly ai percorsi di instradamento)
- <method-list> specifica uno o più metodi accettati dal servizio backend, separati da virgole. Ad esempio, "GET, PUT".
- "type": "DYNAMIC_ROUTING_BACKEND" specifica che si desidera selezionare in modo dinamico il backend in base agli elementi nella richiesta.
- "type": "SINGLE" specifica che si desidera utilizzare una singola variabile di contesto per selezionare in modo dinamico il backend.
- "selector": "<context-table-key>" specifica la tabella di contesto (e la chiave, se appropriato) da cui ottenere il valore della variabile di contesto che determina il backend a cui inviare la richiesta, come indicato di seguito.
  - request.auth[<key>] Utilizzare il valore di una richiesta restituita da una funzione del responsabile autorizzazioni o contenuta in un token Web JSON (JWT) per determinare il backend. <key> è il nome della richiesta. Ad esempio, request.auth[tenant]
  - request.headers[<key>] Utilizzare il valore di un'intestazione della richiesta originale per determinare il backend. <key> è il nome dell'intestazione. Ad esempio, request.headers[Accept]
  - request.host Utilizzare il nome dell'host a cui è stata inviata la richiesta originale (estratto dal campo host dell'intestazione dell'host nella richiesta) per determinare il backend.
  - request.path[<key>] Utilizzare un parametro di percorso della richiesta originale per determinare il backend. <key> è il nome del parametro di percorso. Ad esempio, request.path[region]
  - request.query[<key>] Utilizzare il valore di un parametro di query della richiesta originale per determinare il backend. <key> è il nome del parametro di query. Ad esempio, request.query[state]
  - request.subdomain[<key>] Utilizzare la parte iniziale del nome host a cui è stata inviata la richiesta originale (solo quella parte del nome host non specificata come chiave) per determinare il backend. Si noti che <key> è la parte finale del nome host da non utilizzare. Ad esempio, request.subdomain[example.com]
  - request.usage_plan[id] Utilizzare l'OCID di un piano di utilizzo al quale è stata eseguita la sottoscrizione del client API (identificato da un token client nella richiesta originale) per determinare il backend.
- "key": {...} specifica la regola che deve essere soddisfatta per inviare una richiesta al backend specificato da "backend": {…}.
- "type": "<ANY_OF|WILDCARD>" specifica quanto strettamente il valore della variabile di contesto identificata da <context-table-key> deve corrispondere al valore immesso per <context-variable-value> affinché la richiesta venga inviata al back-end specificato da "backend": {…}. Specificare ANY_OF se il valore della variabile di contesto identificata da <context-table-key> deve corrispondere esattamente al valore specificato per <context-variable-value>. Specificare WILDCARD se il valore della variabile di contesto identificata da <context-table-key> deve corrispondere a un valore contenente i caratteri jolly specificati per <context-variable-value>. La corrispondenza dei valori non fa distinzione tra maiuscole e minuscole se si specifica ANY_OF e viene fatta distinzione tra maiuscole e minuscole se si specifica WILDCARD.
- <context-variable-value> è un valore che probabilmente corrisponde al valore della variabile di contesto identificata da <context-table-key>. È possibile includere più voci "<context-variable-value>" nell'array values:[...], separate da virgole. La richiesta viene inviata al backend specificato da "backend": {…} se i valori corrispondono, come indicato di seguito.
  - Se è stato specificato "type": "ANY_OF", i valori devono corrispondere esattamente. Tenere presente che i valori devono essere univoci all'interno di una singola regola backend e in tutte le regole backend definite per una distribuzione API. La corrispondenza dei valori non fa distinzione tra maiuscole e minuscole se è stato specificato ANY_OF.
  - Se è stato specificato "type": "WILDCARD", è possibile specificare un valore per <context-variable-value> che inizi con o termini con un carattere jolly. Utilizzare il carattere jolly * (asterisco) per indicare zero o più caratteri e/o il carattere jolly + (segno più) per indicare uno o più caratteri. Tenere presente che non è possibile includere più di un carattere jolly in un valore e che non è possibile includere un carattere jolly al centro di un valore. La corrispondenza dei valori fa distinzione tra maiuscole e minuscole se è stato specificato WILDCARD.
  Ad esempio, se si desidera che una richiesta di un client API in grado di accettare una risposta xml (come indicato nell'intestazione Accept della richiesta) venga instradata a un backend che restituisce xml, è possibile specificare:
  - "selector": "request.headers[Accept]"
  - "type": "ANY_OF"
  - "values": ["application/xml"]
- "isDefault": "<true|false>" è un valore booleano facoltativo (true o false) che indica se utilizzare il backend per questa regola se nessuna regola backend corrisponde. Se non specificato, verrà utilizzato il valore predefinito di false.
- "name": "<rule-name>" specifica un nome per la regola. Utilizzare questo nome per identificare il backend quando si fa riferimento a log e metriche.
- <backend-type> specifica il tipo di servizio backend. I valori validi sono ORACLE_FUNCTIONS_BACKEND, HTTP_BACKEND e STOCK_RESPONSE_BACKEND.
- <backend-target> e <identifier> specificano il servizio backend. I valori validi per <backend-target> e <identifier> dipendono dal valore di <backend-type>, come indicato di seguito.
  - Se si imposta <backend-type> su ORACLE_FUNCTIONS_BACKEND, sostituire <backend-target> con functionId e <identifier> con l'OCID della funzione. Ad esempio, "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab5b...". Vedere Aggiunta di una funzione nelle funzioni OCI come backend del gateway API.
  - Se si imposta <backend-type> su HTTP_BACKEND, sostituire <backend-target> con url e <identifier> con l'URL del servizio backend. Ad esempio, "url": "https://api.weather.gov". Vedere Aggiunta di un URL HTTP o HTTPS come backend del gateway API.
  - Se si imposta <backend-type> su STOCK_RESPONSE_BACKEND, sostituire <backend-target> e <identifier> con le coppie chiave-valore appropriate. Vedere Aggiunta di risposte scorte come backend del gateway API.
Ad esempio, la seguente specifica di distribuzione API di base include la selezione backend dinamica che instrada le richieste in base al valore del parametro di query vehicle-type passato nella richiesta. Se il parametro di query vehicle-type ha il valore car, la richiesta viene instradata a cars-api.example.com. Se il parametro di query vehicle-type ha un valore truck o minivan, la richiesta viene instradata a una funzione serverless in Funzioni OCI per l'elaborazione. Se il valore del parametro di query vehicle-type non è car, truck e minivan, la richiesta viene instradata a cars-api.example.com per impostazione predefinita:
```
{
  "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",
              "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"
            }
          }
        ]
      }
    }
  ]
}
```
Salvare il file JSON contenente la specifica di distribuzione API.
Utilizzare la specifica di distribuzione API quando si crea o si aggiorna una distribuzione API nei modi riportati di seguito.
- specificando il file JSON nella console quando si seleziona l'opzione Carica un'interfaccia API esistente
- specificando il file JSON in una richiesta all'API REST del gateway API
Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API.
(Facoltativo) Confermare che l'interfaccia API sia stata distribuita chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Esempi di selezione dinamica dei backend del gateway API

Gli esempi in questa sezione presuppongono la seguente definizione di distribuzione API e la specifica di distribuzione API incompleta in un file JSON:

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

Gli esempi si applicano anche quando si definisce una specifica di distribuzione API utilizzando le finestre di dialogo nella console.

Esempio 1: selezionare il backend per host

È possibile configurare una distribuzione API per selezionare in modo dinamico un backend in base all'host a cui è stata inviata la richiesta originale (estratto dal campo host dell'intestazione host nella richiesta). Questa progettazione consente di definire un gateway API che supporta tenant diversi.

{
  "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 questo esempio, il modo in cui il gateway API risolve una richiesta a https://<gateway-hostname>/marketing/sales dipende dall'host a cui è stata inviata la richiesta originale (estratta dal campo host dell'intestazione host nella richiesta), come indicato di seguito.

Se la richiesta è stata inviata a cars.example.com, la richiesta viene instradata a http://cars-api.example.com.
Se la richiesta è stata inviata a minivans.examplecloud.com o trucks.example.com, la richiesta viene instradata a un backend di funzioni serverless in Funzioni OCI.
Se la richiesta è stata inviata a un altro host, per impostazione predefinita la richiesta viene instradata a http://cars-api.example.com.

Esempio 2: selezionare il backend per sottodominio host

È possibile configurare una distribuzione API per selezionare in modo dinamico un backend basato su un sottodominio nella stringa host a cui è stata inviata la richiesta originale. La stringa host viene estratta dall'intestazione Host nella richiesta e mascherata da una stringa specificata, lasciando il sottodominio utilizzato per instradare la richiesta. Questa progettazione consente di definire un gateway API che supporta tenant diversi.

{
  "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 questo esempio, la modalità di risoluzione di una richiesta a https://<gateway-hostname>/marketing/sales da parte del gateway API dipende dal sottodominio host a cui è stata inviata la richiesta originale, come riportato di seguito.

se la richiesta è stata inviata a cars.example.com, la richiesta viene indirizzata a http://cars-api.example.com
se la richiesta è stata inviata a minivans.example.com o trucks.example.com, la richiesta viene instradata a un backend di funzioni serverless in Funzioni OCI
se la richiesta è stata inviata a un sottodominio diverso di example.com (ad esempio car.example.com o sedan.example.com), la richiesta viene instradata a http://cars-api.example.com per impostazione predefinita

Esempio 3: selezionare il backend dal sottodominio host (modifica del nome host nell'URL backend)

È possibile configurare una distribuzione API per selezionare in modo dinamico un backend basato su un sottodominio nella stringa host a cui è stata inviata la richiesta originale. La stringa host viene estratta dall'intestazione Host nella richiesta e mascherata da una stringa specificata, lasciando il sottodominio utilizzato per instradare la richiesta. Per una convalida aggiuntiva, è possibile includere la maschera del sottodominio come variabile di contesto nell'URL backend per assicurarsi che le richieste vengano instradate solo ai backend che si desidera esporre.

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

se la richiesta è stata inviata a cars.example.com o hatchbacks.example.com, la richiesta viene indirizzata a http://cars-api.example.com o http://hatchbacks-api.example.com
se la richiesta è stata inviata a un sottodominio diverso di example.com (ad esempio suvs.example.com o sedans.example.com), la richiesta non riesce.

Se si desidera modificare il nome host nell'URL backend includendo una variabile di contesto come illustrato in questo esempio, tenere presente quanto riportato di seguito.

È possibile modificare l'URL backend solo utilizzando la variabile di contesto specificata per selector.
Per applicare la lista dei backend consentiti, non impostare "isDefault: "true" per alcuna regola.

Esempio 4: selezionare il backend per piano di utilizzo

È possibile configurare una distribuzione API per selezionare in modo dinamico un backend in base all'OCID di un piano di utilizzo al quale il client API è sottoscritto (identificato da un token client nella richiesta originale). L'OCID del piano di utilizzo viene memorizzato nella variabile di contesto 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"
            }
          }
        ]
      }
    }
  ]
}

In questo esempio, la modalità di risoluzione di una richiesta a https://<gateway-hostname>/marketing/sales da parte del gateway API dipende dal piano di utilizzo al quale è sottoscritto il client API. Sono stati definiti due piani di utilizzo, come indicato di seguito.

Free Tier, che contiene l'OCID ocid1.usageplan.oc1..aaaaaaaaab______gap. Quando questo OCID è il valore della variabile di contesto request.usage_plan[id], la richiesta viene instradata a http://dev.example.com/. Il piano di utilizzo Free Tier viene utilizzato come predefinito anche se la richiesta non include un token client.
Premium Tier, che contiene l'OCID ocid1.usageplan.oc1..aaaaaaaaay______lcf. Quando questo OCID è il valore della variabile di contesto request.usage_plan[id], la richiesta viene instradata a http://api.example.com

Esempio 5: selezionare il backend per parametro intestazione

È possibile configurare una distribuzione API per selezionare in modo dinamico un backend in base a un parametro passato nell'intestazione della richiesta originale.

{
  "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 questo esempio, la modalità di risoluzione di una richiesta a https://<gateway-hostname>/marketing/sales da parte del gateway API dipende dal valore dell'intestazione Accept nella richiesta originale, come riportato di seguito.

se l'intestazione Accept richiede una risposta in formato application/json, la richiesta viene instradata a http://api.example.com
se l'intestazione Accept richiede una risposta in formato application/xml, la richiesta viene instradata a http://xml.example.com

Esempio 6: selezionare il backend mediante il parametro di autenticazione

È possibile configurare una distribuzione API per selezionare in modo dinamico un backend in base a un parametro di autenticazione (noto anche come 'claim') restituito da una funzione del responsabile autorizzazioni o contenuto in un token Web JSON (JWT).

{
  "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 questo esempio, la modalità di risoluzione di una richiesta a https://<gateway-hostname>/marketing/sales da parte del gateway API dipende dal valore della richiesta tenant restituita da una funzione del responsabile autorizzazioni, come riportato di seguito.

se la variabile di contesto request.auth[tenant] è impostata su tenant-cars, la richiesta viene instradata a http://cars-api.example.com
se la variabile di contesto request.auth[tenant] è impostata su tenant-trucks, la richiesta viene instradata a http://trucks-api.example.com

Esempio 7: selezionare il backend per parametro di query

È possibile configurare una distribuzione API per selezionare in modo dinamico un backend in base a un parametro di query passato dalla richiesta originale.

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

In questo esempio, la modalità di risoluzione di una richiesta a https://<gateway-hostname>/marketing/sales da parte del gateway API dipende dal valore del parametro di query vehicle-type passato dalla richiesta originale, come riportato di seguito.

Se il parametro di query vehicle-type ha il valore car, la richiesta viene instradata a cars-api.example.com.
Se il parametro di query vehicle-type ha un valore truck o minivan, la richiesta viene instradata a una funzione serverless in Funzioni OCI per l'elaborazione.
Se il valore del parametro di query vehicle-type non è car, truck e minivan, la richiesta viene instradata a cars-api.example.com per impostazione predefinita:

Documentazione di Oracle Cloud Infrastructure