Oracle Cloud Infrastructure - Dokumentation

Kontextabhängige Variablen zu Policys und HTTP-Backend-Definitionen hinzufügen

Erfahren Sie, wie Sie Parameter in API-Aufrufen mit API-Gateway-Kontextvariablen verwenden.

Aufrufe an APIs, die in einem API-Gateway bereitgestellt sind, umfassen in der Regel Parameter, die Sie bei der Definition der folgenden Elemente in API-Deployment-Spezifikationen verwenden sollten:

  • Anforderungs-Policys und Antwort-Policys
  • HTTP- und HTTPS-Backends

Damit Sie Parameter verwenden können, die in API-Aufrufen enthalten sind, speichert der API Gateway-Service die Werte der folgenden Parametertypen in temporären "Kontexttabellen":

Jeder Datensatz in einer Kontexttabelle wird durch einen eindeutigen Schlüssel identifiziert.

Beim Definieren von Anforderungs- und Antwort-Policys sowie von HTTP- und HTTPS-Backends können Sie den Wert eines Parameters in einer Kontexttabelle mit einer "kontextabhängigen Variablen" referenzieren. Eine kontextabhängige Variable hat das Format <context-table-name>[<key>]. Dabei gilt:

  • <context-table-name> ist eine der Optionen request.path, request.query, request.headers, request.auth, request.cert oder request.host
  • <key> ist eines der folgenden Elemente:
    • Ein Pfadparametername, der in der API-Deployment-Spezifikation definiert ist
    • Ein Abfrageparametername, der in der Anforderung an die API enthalten ist
    • Ein Headername, der in der Anforderung an die API enthalten ist
    • Ein Authentifizierungsparametername, der von einer Autorisiererfunktion zurückgegeben wird oder in einem JWT-Token enthalten ist
    • Der Name [client_base64], der ein erfolgreich validiertes, Base64-codiertes Zertifikat darstellt, das von einem API-Client während eines mTLS-Handshakes präsentiert wird
    • den abschließenden Teil des zu ignorierenden Hostnamens (bei der Erfassung des führenden Teils des Hostnamens, an den die ursprüngliche Anforderung gesendet wurde)
    • Name eines Hosts, an den die Anforderung gesendet wurde (aus dem Headerfeld Host in der Anforderung extrahiert)

Wenn die kontextabhängige Variable innerhalb einer Zeichenfolge in der API-Deployment-Spezifikation enthalten sein soll (z.B. in der URL-Eigenschaft einer HTTP-Backend-Definition), verwenden Sie das Format ${<context-table-name>[<key>]}.

Beispiel: Die kontextabhängige Variable request.path[region] im nachfolgenden Beispiel gibt den Wert des Datensatzes zurück, der durch den region-Schlüssel in der request.path-Kontexttabelle identifiziert wird.

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

Beachten Sie dabei Folgendes:

  • In der Kontexttabelle wird ein einzelner Datensatz für jeden diskreten Parameter in einer HTTP-Anforderung erstellt. Wenn die HTTP-Anforderung zwei (oder mehr) Parameter desselben Typs und mit demselben Namen enthält, wird der Wert jedes Parameters mit diesem Namen im selben Datensatz in der Kontexttabelle gespeichert und durch denselben Schlüssel identifiziert. Es kann jedoch anstelle einer kontextabhängigen Variablen nur der erste Wert im Kontexttabellendatensatz ersetzt werden. Wenn Sie eine kontextabhängige Variable hinzufügen, für die mehrere Werte im Kontexttabellendatensatz vorhanden sein können, und anstelle der kontextabhängigen Variablen der erste Wert im Kontexttabellendatensatz ersetzt werden soll, fügen Sie die kontextabhängige Variable der API-Deployment-Spezifikation im Format ${<context-table-name>[<key>]} hinzu.
  • Wenn ein Parameterwert Sonderzeichen enthält, die codiert wurden, wird die Codierung beibehalten, wenn der Wert in der Kontexttabelle gespeichert wird. Wenn der Wert durch eine kontextabhängige Variable ersetzt wird, wird anstelle der kontextabhängigen Variablen der codierte Wert ersetzt. Beispiel: Wenn San José in einem Abfrageparameter als San+Jos&#233; enthalten ist, wird anstelle der kontextabhängigen Variablen die codierte Version durch diesen Abfrageparameter ersetzt.
  • Wenn in der angegebenen Kontexttabelle kein Schlüssel einer kontextabhängigen Variablen vorhanden ist, wird anstelle der kontextabhängigen Variablen eine leere Zeichenfolge ersetzt.
  • Wenn der Schlüssel einer kontextabhängigen Variablen einen Punkt enthält, wird der Punkt als beliebiges anderes Zeichen behandelt. Er wird nicht als Indikator einer hierarchischen Beziehung zwischen den Zeichenfolgen auf beiden Seiten behandelt.
  • Wenn ein Pfadparameter einen Platzhalter enthält (z.B. generic_welcome*), wird der Pfadparameter ohne Platzhalter als Schlüssel verwendet.

  • Sie können eine Kontextvariable als Pfadsegment in die URL-Eigenschaft einer HTTP-Backend-Definition aufnehmen, jedoch nicht als Abfrageparameter. Beispiel:

    • Sie können die Kontextvariable request.query[state] als Pfadsegment in der URL-Eigenschaft verwenden, wie in der folgenden gültigen HTTP-Backend-Definition dargestellt: 

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

    • Sie können die Kontextvariable request.query[state] nicht als Abfrageparameter in der URL-Eigenschaft verwenden, wie in der folgenden ungültigen HTTP-Backend-Definition dargestellt: 

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

    Wenn Sie eine Kontextvariable als Abfrageparameter übergeben möchten, verwenden Sie eine Abfrageparameter-Transformationsanforderungs-Policy, anstatt die Kontextvariable als Abfrageparameter in die URL-Eigenschaft aufzunehmen (siehe Abfrageparameter-Transformationsanforderungs-Policys hinzufügen).

Beispiele

In den Beispielen in diesem Abschnitt wird von der folgenden API-Deployment-Definition und grundlegenden 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": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov"
        }
      }
    ]
  },
  "freeformTags": {},
  "definedTags": {}
}

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

Beispiel 1: Abfragepfadparameter in einer Definition

Sie können einen Pfadparameter in der API-Deployment-Spezifikation definieren und ihn dann an anderer Stelle in der API-Deployment-Spezifikation als Kontextvariable verwenden.

In diesem Beispiel wird der Pfadparameter region erstellt und in der kontextabhängigen Variablen request.path[region] in der HTTP-Backend-Definition verwendet.

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

In diesem Beispiel wird eine Anforderung wie https://<gateway-hostname>/marketing/weather/west zu https://api.weather.gov/west aufgelöst.

Beispiel 2: Unterschiedliche Typen von kontextabhängigen Variablen in derselben Definition

Sie können verschiedene Typen von kontextabhängigen Variablen in dieselbe Definition in der API-Deployment-Spezifikation aufnehmen.

In diesem Beispiel wird Folgendes in der HTTP-Backend-Definition verwendet:

  • Die kontextabhängige Variable eines Pfadparameters, request.path[region]
  • Die kontextabhängige Variable eines Abfrageparameters, request.query[state]
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
        }
      }

In diesem Beispiel wird eine Anforderung wie https://<gateway-hostname>/marketing/weather/west?state=california zu https://api.weather.gov/west/california aufgelöst.

Beispiel 3: Mehrere kontextvariablen desselben Typs in derselben Definition

Sie können Kontextvariablen desselben Typs mehrmals in dieselbe Definition aufnehmen.

In diesem Beispiel wird Folgendes in der HTTP-Backend-Definition verwendet:

  • Die kontextabhängige Variable eines Pfadparameters, request.path[region]
  • Zwei kontextabhängige Variablen eines Abfrageparameters, request.query[state] und 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 diesem Beispiel wird eine Anforderung wie https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont zu https://api.weather.gov/west/california/fremont aufgelöst.

Beispiel 4: Mehrere Werte für denselben Parameter

Eine HTTP-Anforderung kann oftmals denselben Abfrageparameter mehrmals enthalten. Der API-Gateway-Service speichert den Wert jedes Parameters mit demselben Namen im selben Datensatz in der Kontexttabelle. In der API-Deployment-Spezifikation ist es jedoch normalerweise so, dass nur ein einzelner Wert durch eine kontextabhängige Variable ersetzt werden kann. In diesen Fällen können Sie angeben, dass anstelle einer kontextabhängigen Variablen nur der erste in der Kontexttabelle für einen Schlüssel erfasste Wert ersetzt werden soll, indem Sie die kontextabhängige Variable in ${...} einschließen.

Beispiel: Eine gültige Anforderung wie "https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont" enthält zwei Vorkommen des Abfrageparameters city. Bei Empfang der HTTP-Anforderung schreibt der API-Gateway-Service beide Werte des Abfrageparameters city (fremont und belmont) in denselben Datensatz in der request.query-Tabelle. Wenn die Definition eines HTTP-Backends ${request.query[city]} enthält, wird anstelle der kontextabhängigen Variablen nur der erste Wert im Datensatz ersetzt.

In diesem Beispiel wird Folgendes in der HTTP-Backend-Definition verwendet:

  • Die kontextabhängige Variable eines Pfadparameters, request.path[region]
  • Zwei kontextabhängige Variablen eines Abfrageparameters, request.query[state] und 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 diesem Beispiel wird eine Anforderung wie https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont zu https://api.weather.gov/west/california/fremont aufgelöst. Beachten Sie, dass nur fremont (als erster Wert im request.query-Kontexttabellendatensatz, der durch den city-Schlüssel identifiziert wird) durch die kontextabhängige Variable request.query[city] ersetzt wird.

Beispiel 5: Parameterwert enthält codierte Sonderzeichen

Wenn eine HTTP-Anforderung Sonderzeichen (z.B. das Zeichen é oder ein Leerzeichen) enthält, die codiert wurden, wird der Wert in seiner codierten Form in der Kontexttabelle gespeichert. Wenn der Wert aus der Kontexttabelle durch eine Kontextvariable ersetzt wird, wird die Codierung beibehalten.

In diesem Beispiel wird Folgendes in der HTTP-Backend-Definition verwendet:

  • Die kontextabhängige Variable eines Pfadparameters, request.path[region]
  • Die kontextabhängige Variable eines Abfrageparameters, 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 diesem Beispiel wird eine Anforderung wie https://<gateway-hostname>/marketing/weather/west?city=San+Jos&#233; zu https://api.weather.gov/west/california/San+Jos&#233; aufgelöst.

Beispiel 6: Headerparameter in einer Definition

Sie können Werte, die in den Headern einer Anforderung übergeben werden, als kontextabhängige Variablen in eine Definition aufnehmen. Wenn die Anforderung einen Header enthält, wird der Wert des Headers in der request.headers-Tabelle gespeichert, und der Name des Headers wird als Schlüssel verwendet.

In diesem Beispiel wird Folgendes in der HTTP-Backend-Definition verwendet:

  • Die kontextabhängige Variable eines Pfadparameters, request.path[region]
  • Die kontextabhängige Variable eines Headerparameters, 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 diesem Beispiel enthielt eine Anforderung wie https://<gateway-hostname>/marketing/weather/west einen X-Api-Key-Header mit dem Wert abc123def456fhi789. Die Anforderung wird zu https://api.weather.gov/west/abc123def456fhi789 aufgelöst.

Beispiel 7: Authentifizierungsparameter in einer Definition

Sie können Werte, die von einer Autorisiererfunktion zurückgegeben werden oder in einem JWT-Token enthalten sind, als kontextabhängige Variablen in eine Definition aufnehmen:

  • Eine Autorisiererfunktion validiert das Token, das ein API-Client beim Aufrufen des API Gateway-Service übergeben hat. Die Autorisiererfunktion gibt eine Antwort zurück, die Informationen wie die Gültigkeit der Autorisierung, Informationen zum Endbenutzer, Zugriffsgeltungsbereich und eine Reihe von Claims in Schlüssel/Wert-Paaren enthält. Je nach Autorisierungstoken können die Informationen im Token enthalten sein, oder die Autorisiererfunktion ruft Endpunkte auf, die vom Autorisierungsserver zur Validierung des Tokens und zum Abrufen von Informationen zum Endbenutzer bereitgestellt werden. Wenn der API Gateway-Service ein Schlüssel/Wert-Paar von der Autorisiererfunktion empfängt, wird das Schlüssel/Wert-Paar in der Tabelle request.auth als Authentifizierungsparameter gespeichert.
  • Ein JWT-Token kann optional einen benutzerdefinierten Claim namens scope enthalten, der aus einem Schlüssel/Wert-Paar besteht. Nach der Validierung des JWT-Tokens speichert der API Gateway-Service das Schlüssel-Wert-Paket als Authentifizierungsparameter in der Tabelle request.auth.

    Im Fall des OpenID Connect-Autorisierungsflusses werden zwei Token mit dem Namen id_token (immer JWT-codiert) und access_token (kann JWT-codiert sein) zurückgegeben. Der API Gateway-Service speichert die Tokenwerte in den Kontextvariablen request.auth[id_token] und request.auth[access_token] sowie benutzerdefinierte Claims in den Kontextvariablen request.auth[id_token_claims][<claim-name>] bzw. request.auth[access_token_claims][<claim-name>].

In diesem Beispiel wird das Schlüssel/Wert-Paar verwendet, das von einer Autorisiererfunktion als Kontextvariable request.auth[region] des Authentifizierungsparameters in der HTTP-Backend-Definition zurückgegeben wird.

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

Angenommen, die Autorisiererfunktion ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq validiert das Token, das ein API-Client in einem Aufruf an den API Gateway-Service übergeben hat. Die Autorisiererfunktion gibt eine Antwort an den API Gateway-Service zurück, die die mit dem Endbenutzer verknüpfte Region als Schlüssel/Wert-Paar und den Zugriffsgeltungsbereich des authentifizierten Endbenutzers enthält. Wenn der API Gateway-Service das Schlüssel/Wert-Paar empfängt, wird das Schlüssel/Wert-Paar in der Tabelle request.auth als Authentifizierungsparameter gespeichert.

In diesem Beispiel wird eine Anforderung wie https://<gateway-hostname>/marketing/weather von einem Endbenutzer namens "jdoe" mit einem API-Client gesendet. Die Autorisiererfunktion validiert das Token, das der API-Client in der Anforderung übergeben hat, und bestimmt auch, dass der Benutzer "jdoe" den Zugriffsgeltungsbereich "weatherwatcher" hat. Die Autorisiererfunktion identifiziert, dass der Benutzer "jdoe" mit der Region "west" verknüpft ist. Die Autorisiererfunktion gibt den Zugriffsgeltungsbereich des Benutzers "jdoe" an den API Gateway-Service zurück. Außerdem gibt sie die dem Benutzer "jdoe" zugeordnete Region zurück. Der API Gateway-Service speichert die dem Benutzer "jdoe" zugeordnete Region als Authentifizierungsparameter. Die HTTP-Backend-Definition gibt an, dass Endbenutzer mit dem Zugriffsgeltungsbereich "weatherwatcher" auf das HTTP-Backend zugreifen dürfen. Der API Gateway-Service verwendet den Wert der Kontextvariablen request.auth[region] des Authentifizierungsparameters in der Anforderung. Die Anforderung wird zu https://api.weather.gov/west aufgelöst.

Beispiel 8: TLS-Zertifikatsparameter in einer Definition

Sie können eine Base64-codierte Version des TLS-Zertifikats aufnehmen, die von einem API-Client während eines mTLS-Handshakes als Kontextvariable in einer Definition dargestellt wird. Die Base64-codierte Version des TLS-Zertifikats wird in der Tabelle request.cert gespeichert, wobei der Name client_base64 als Schlüssel verwendet wird. Siehe mTLS-Support zu API-Deployments hinzufügen.

In diesem Beispiel wird Folgendes in der HTTP-Backend-Definition verwendet:

  • die Zertifikatskontextvariable, 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 diesem Beispiel wird der Anforderung ein Header mit dem Namen certificate-header hinzugefügt, und der Wert der Base64-codierten Version des TLS-Zertifikats wird vom API-Client beim mTLS-Handshake mit dem API-Gateway angezeigt.