Documentazione di Oracle Cloud Infrastructure

Aggiunta di variabili di contesto ai criteri e alle definizioni backend HTTP

Scopri come utilizzare i parametri nelle chiamate API utilizzando le variabili di contesto di API Gateway.

Le chiamate alle API distribuite in un gateway API in genere includono parametri che si desidera utilizzare durante la definizione degli elementi riportati di seguito nelle specifiche di distribuzione API.

  • criteri di richiesta e criteri di risposta
  • Back-end HTTP e HTTPS

Per consentire l'uso dei parametri inclusi nelle chiamate API, il servizio Gateway API salva i valori dei seguenti tipi di parametri nelle 'tabelle di contesto' temporanee:

Ogni record in una tabella di contesto è identificato da una chiave univoca.

Quando si definiscono i criteri di richiesta e risposta e i backend HTTP e HTTPS, è possibile fare riferimento al valore di un parametro in una tabella di contesto utilizzando una 'variabile di contesto'. Una variabile di contesto ha il formato <context-table-name>[<key>], dove:

  • <context-table-name> è uno dei seguenti: request.path, request.query, request.headers, request.auth, request.cert o request.host
  • <key> è uno dei seguenti:
    • un nome di parametro del percorso definito nella specifica di distribuzione API
    • un nome di parametro di query incluso nella richiesta all'API
    • un nome di intestazione incluso nella richiesta all'API
    • un nome di parametro di autenticazione restituito da una funzione del responsabile autorizzazioni o contenuto in un token JWT
    • il nome [client_base64], che rappresenta un certificato convalidato correttamente, con codifica Base64, presentato da un client API durante un handshake mTLS
    • la parte finale del nome host da ignorare (quando si acquisisce la parte iniziale del nome host a cui è stata inviata la richiesta originale)
    • il nome di un host a cui è stata inviata la richiesta (estratto dal campo dell'intestazione Host nella richiesta)

Se si desidera includere la variabile di contesto all'interno di una stringa nella specifica di distribuzione API (ad esempio, nella proprietà URL di una definizione backend HTTP), utilizzare il formato ${<context-table-name>[<key>]}.

Ad esempio, la variabile di contesto request.path[region] nell'esempio riportato di seguito restituisce il valore del record identificato dalla chiave region nella tabella di contesto request.path.

{
  "routes": [
    {
      "path": "/weather/{region}",
      "methods": ["GET"],
      "backend": {
        "type": "HTTP_BACKEND",
        "url": "https://api.weather.gov/${request.path[region]}"
      }
    }
  ]
}

Nota:

  • Nella tabella di contesto viene creato un singolo record per ogni parametro discreto in una richiesta HTTP. Se la richiesta HTTP include due (o più) parametri dello stesso tipo e con lo stesso nome, il valore di ogni parametro con tale nome viene salvato nello stesso record nella tabella di contesto e identificato dalla stessa chiave. Tuttavia, solo il primo valore nel record della tabella di contesto può essere sostituito al posto di una variabile di contesto. Quando si aggiunge una variabile di contesto per la quale possono esistere più valori nel record della tabella di contesto e si desidera che il primo valore del record della tabella di contesto venga sostituito al posto della variabile di contesto, aggiungere la variabile di contesto alla specifica di distribuzione API nel formato ${<context-table-name>[<key>]}
  • Se un valore di parametro include caratteri speciali che sono stati codificati, la codifica viene conservata quando il valore viene salvato nella tabella di contesto. Quando il valore viene sostituito con una variabile di contesto, il valore codificato viene sostituito al posto della variabile di contesto. Ad esempio, se San José è incluso in un parametro di query come San+Jos&#233;, la versione codificata è quella che verrà sostituita al posto della variabile di contesto per quel parametro di query.
  • Se una chiave di variabile di contesto non esiste nella tabella di contesto specificata, al posto della variabile di contesto viene sostituita una stringa vuota.
  • Se una chiave di variabile di contesto contiene un punto, il punto viene considerato come qualsiasi altro carattere. Non viene considerato come un indicatore di una relazione padre-figlio tra le stringhe su entrambi i lati.
  • Se un parametro di percorso include un carattere jolly (ad esempio, generic_welcome*), come chiave viene utilizzato il parametro di percorso senza il carattere jolly.

  • È possibile includere una variabile di contesto come segmento di percorso nella proprietà URL di una definizione backend HTTP, ma non come parametro di query. Ad esempio:

    • È possibile utilizzare la variabile di contesto request.query[state] come segmento di percorso nella proprietà URL, come mostrato nella seguente definizione backend HTTP valida: 

            {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
        }
      }

    • Impossibile utilizzare la variabile di contesto request.query[state] come parametro di query nella proprietà URL, come mostrato nella seguente definizione backend HTTP non valida: 

            {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}?state=${request.query[state]}"
        }
      }

    Se si desidera passare una variabile di contesto come parametro di query, utilizzare un criterio di richiesta di trasformazione dei parametri di query anziché includere la variabile di contesto come parametro di query nella proprietà URL (vedere Aggiunta dei criteri di richiesta di trasformazione dei parametri di query).

Esempi

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

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

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

Esempio 1: parametro del percorso di query in una definizione

È possibile definire un parametro di percorso nella specifica di distribuzione API, quindi utilizzarlo altrove nella specifica di distribuzione API come variabile di contesto.

Questo esempio crea un parametro di percorso, region, e lo utilizza in una variabile di contesto request.path[region] nella definizione backend HTTP.

      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}"
        }
      }

In questo esempio, una richiesta come https://<gateway-hostname>/marketing/weather/west viene risolta in https://api.weather.gov/west.

Esempio 2: diversi tipi di variabile di contesto nella stessa definizione

È possibile includere diversi tipi di variabile di contesto nella stessa definizione nella specifica di distribuzione API.

In questo esempio viene utilizzato quanto riportato di seguito nella definizione backend HTTP.

  • una variabile di contesto del parametro di percorso, request.path[region]
  • una variabile di contesto del parametro di query, request.query[state]
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
        }
      }

In questo esempio, una richiesta come https://<gateway-hostname>/marketing/weather/west?state=california viene risolta in https://api.weather.gov/west/california.

Esempio 3: più variabili di contesto dello stesso tipo nella stessa definizione

È possibile includere più volte lo stesso tipo di variabile di contesto nella stessa definizione.

In questo esempio viene utilizzato quanto riportato di seguito nella definizione backend HTTP.

  • una variabile di contesto del parametro di percorso, request.path[region]
  • due variabili di contesto dei parametri di query, request.query[state] e request.query[city]
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}/${request.query[city]}"
        }
      }

In questo esempio, una richiesta come https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont viene risolta in https://api.weather.gov/west/california/fremont.

Esempio 4: più valori per lo stesso parametro

È spesso valido per una richiesta HTTP includere più volte lo stesso parametro di query. Il servizio API Gateway salva il valore di ogni parametro con lo stesso nome nello stesso record nella tabella di contesto. Tuttavia, nella specifica di distribuzione API, in genere è possibile sostituire una variabile di contesto con un solo valore. In questi casi, è possibile indicare che al posto di una variabile di contesto viene sostituito solo il primo valore registrato nella tabella di contesto per una chiave racchiudendo la variabile di contesto in ${...}.

Ad esempio, una richiesta valida come "https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont" ha due occorrenze del parametro di query city. Alla ricezione della richiesta HTTP, il servizio API Gateway scrive entrambi i valori del parametro di query city (fremont e belmont) nello stesso record nella tabella request.query. Quando la definizione di un backend HTTP include ${request.query[city]}, al posto della variabile di contesto viene sostituito solo il primo valore del record.

In questo esempio viene utilizzato quanto riportato di seguito nella definizione backend HTTP.

  • una variabile di contesto del parametro di percorso, request.path[region]
  • due variabili di contesto dei parametri di query, request.query[state] e request.query[city] 
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}/${request.query[city]}"
        }
      }

In questo esempio, una richiesta come https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont viene risolta in https://api.weather.gov/west/california/fremont. Si noti che solo fremont (come primo valore nel record della tabella di contesto request.query identificato dalla chiave city) viene sostituito dalla variabile di contesto request.query[city].

Esempio 5: il valore del parametro include caratteri speciali codificati

Se una richiesta HTTP include caratteri speciali (ad esempio, il carattere é, lo spazio) che sono stati codificati, il valore viene memorizzato nella tabella di contesto nel relativo formato codificato. Quando il valore della tabella di contesto viene sostituito da una variabile di contesto, la codifica viene conservata.

In questo esempio viene utilizzato quanto riportato di seguito nella definizione backend HTTP.

  • una variabile di contesto del parametro di percorso, request.path[region]
  • una variabile di contesto del parametro di query, request.query[city]
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}/${request.query[city]}"
        }
      }

In questo esempio, una richiesta come https://<gateway-hostname>/marketing/weather/west?city=San+Jos&#233; viene risolta in https://api.weather.gov/west/california/San+Jos&#233;.

Esempio 6: parametri di intestazione in una definizione

È possibile includere i valori passati nelle intestazioni di una richiesta come variabili di contesto in una definizione. Se la richiesta include un'intestazione, il valore dell'intestazione viene memorizzato nella tabella request.headers e come chiave viene utilizzato il nome dell'intestazione.

In questo esempio viene utilizzato quanto riportato di seguito nella definizione backend HTTP.

  • una variabile di contesto del parametro di percorso, request.path[region]
  • variabile di contesto di un parametro di intestazione, request.headers[X-Api-Key]
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.headers[X-Api-Key]}"
        }
      }

In questo esempio, una richiesta come https://<gateway-hostname>/marketing/weather/west includeva un'intestazione X-Api-Key con il valore abc123def456fhi789. La richiesta viene risolta in https://api.weather.gov/west/abc123def456fhi789.

Esempio 7: parametri di autenticazione in una definizione

È possibile includere valori restituiti da una funzione del responsabile autorizzazioni o contenuti in un token JWT come variabili di contesto in una definizione:

  • Una funzione del responsabile autorizzazioni convalida il token passato da un client API durante la chiamata al servizio Gateway API. La funzione del responsabile autorizzazioni restituisce una risposta che include informazioni quali la validità dell'autorizzazione, le informazioni sull'utente finale, l'ambito di accesso e una serie di richieste nelle coppie chiave-valore. A seconda del token di autorizzazione, le informazioni potrebbero essere contenute nel token oppure la funzione del responsabile autorizzazioni potrebbe richiamare gli endpoint forniti dal server di autorizzazione per convalidare il token e recuperare le informazioni sull'utente finale. Quando il servizio API Gateway riceve una coppia chiave-valore dalla funzione del responsabile autorizzazioni, salva la coppia chiave-valore nella tabella request.auth come parametro di autenticazione.
  • Un token JWT può facoltativamente includere una richiesta personalizzata denominata scope, che comprende una coppia chiave-valore. Una volta convalidato il token JWT, il servizio API Gateway salva la coppia chiave-valore nella tabella request.auth come parametro di autenticazione.

    Nel caso del flusso di autorizzazione OpenID Connect, vengono restituiti due token denominati id_token (sempre codificati in JWT) e access_token (può essere codificato in JWT). Il servizio API Gateway salva i valori del token nelle variabili di contesto request.auth[id_token] e request.auth[access_token], insieme alle richieste personalizzate nelle variabili di contesto request.auth[id_token_claims][<claim-name>] e request.auth[access_token_claims][<claim-name>].

In questo esempio viene utilizzata la coppia chiave-valore restituita da una funzione del responsabile autorizzazioni come variabile di contesto del parametro di autenticazione request.auth[region] nella definizione backend HTTP.

  {
    "requestPolicies": {
      "authentication": {
        "type": "CUSTOM_AUTHENTICATION",
        "isAnonymousAccessAllowed": false,
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
        "tokenHeader": "Authorization"
      }
    },
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.auth[region]}"
        },
        "requestPolicies": {
          "authorization": {
            "type": "ANY_OF",
            "allowedScope": [ "weatherwatcher" ]
          }
        }
      }
    ]
  }

Si supponga che la funzione del responsabile autorizzazioni ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq convalida il token passato da un client API in una chiamata al servizio API Gateway. La funzione del responsabile autorizzazioni restituisce una risposta al servizio API Gateway che include l'area associata all'utente finale come coppia chiave-valore e anche l'ambito di accesso dell'utente finale autenticato. Quando il servizio API Gateway riceve la coppia chiave-valore, salva la coppia chiave-valore nella tabella request.auth come parametro di autenticazione.

In questo esempio, una richiesta come https://<gateway-hostname>/marketing/weather viene effettuata da un jdoe dell'utente finale utilizzando un client API. La funzione del responsabile autorizzazioni convalida il token passato dal client API nella richiesta e determina inoltre che jdoe dispone dell'ambito di accesso "weatherwatcher". La funzione del responsabile autorizzazioni identifica che jdoe è associato all'area occidentale. La funzione del responsabile autorizzazioni restituisce l'ambito di accesso di jdoe al servizio API Gateway, insieme all'area associata a jdoe. Il servizio Gateway API salva l'area associata a jdoe come parametro di autenticazione. La definizione backend HTTP specifica che gli utenti finali con l'ambito di accesso "weatherwatcher" possono accedere al backend HTTP. Il servizio API Gateway utilizza il valore della variabile di contesto del parametro di autenticazione request.auth[region] nella richiesta. La richiesta viene risolta in https://api.weather.gov/west.

Esempio 8: parametro del certificato TLS in una definizione

È possibile includere una versione del certificato TLS con codifica Base64 presentata da un client API durante un handshake mTLS come variabile di contesto in una definizione. La versione con codifica Base64 del certificato TLS viene memorizzata nella tabella request.cert, con il nome client_base64 utilizzato come chiave. Vedere Aggiunta del supporto mTLS alle distribuzioni API.

In questo esempio viene utilizzato quanto riportato di seguito nella definizione backend HTTP.

  • la variabile di contesto del certificato, request.cert[client_base64]
  {
    "requestPolicies": {
      "mutualTls":{
        "isVerifiedCertificateRequired": true,
        "allowedSans": ["api.weather.com"]
      }
    },
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov"
        },
        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items":[
                {
                  "name": "certificate-header",
                  "values": ["${request.cert[client_base64]}"]
                }
              ]
            }
          }
        }
      }
    ]
  }

In questo esempio, viene aggiunta un'intestazione denominata certificate-header alla richiesta e viene fornito il valore della versione codificata Base64 del certificato TLS presentato dal client API durante l'handshake mTLS con il gateway API.