Datenübergabe und -übernahme durch den Backend-Dienst

Wenn ein API-Client eine Anfrage an eine in API Gateway bereitgestellte API stellt, kann der Client einige oder alle der folgenden Informationen als Teil der Anfrage übergeben:

Anfrageheader
Abfrageparameter
Formulardaten
XML- oder JSON-Nutzlasten
Anfragepfade

Beim Erstellen der Antwort auf die API-Anfrage kann der Back-End-Dienst unter anderem folgende Daten an den API-Client zurückgeben:

Antwortheader
XML- oder JSON-Nutzlasten

In diesem Dokument wird beschrieben, wie diese Daten an den und vom Back-End-Dienst übergeben werden.

Wie werden Anfragedaten an den Backend-Dienst übergeben?

Alle Daten in der Anfrage vom API-Client werden unverändert an den Back-End-Dienst übergeben. Der Back-End-Dienst hat dann die Aufgabe, die Anfragedaten im Rahmen der Verarbeitung der Anfrage zu parsen.

Wie werden Antwortdaten an den API-Client zurückgegeben?

Alle in der Antwort vom Back-End-Dienst empfangenen Daten werden unverändert an den API-Client übergeben. Der API-Client muss dann die in der Antwort zurückgegebenen Daten verarbeiten.

Wie wird die Anfrage-URL an den Back-End-Dienst übergeben?

Die URL, die für eine Anfrage an den Back-End-Dienst verwendet wird, wird von der Erweiterung x-google-backend gesteuert. In diesem Abschnitt werden die Optionen zum Konfigurieren der Back-End-Dienst-URL beschrieben.

Adresse und Pfad des Back-End-Dienstes in der OpenAPI-Spezifikation festlegen

In der OpenAPI-Spezifikation, die Sie zum Erstellen einer API-Konfiguration verwenden, verwenden Sie die Erweiterung x-google-backend, um die URL des Back-End-Dienstes anzugeben. Sie geben den Back-End-Dienst beispielsweise in der folgenden Form an:

Backend	x-google-backend
Cloud Functions	x-google-backend: address: https://`GCP_REGION`-`PROJECT_ID`.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://hello-`HASH`.a.run.app
App Engine-Standardumgebung	x-google-backend: address: https://`PROJECT_ID`.appspot.com

Backend

x-google-backend

Cloud Functions


x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello

Cloud Run


x-google-backend:
  address: https://hello-HASH.a.run.app

App Engine-Standardumgebung


x-google-backend:
  address: https://PROJECT_ID.appspot.com

In diesen Beispielen gilt Folgendes:

GCP_REGION gibt die GCP-Region für das bereitgestellte Back-End an.
PROJECT_ID die Google Cloud-Projekt-ID angibt.
HASH gibt den eindeutigen Hash-Code an, der beim Erstellen des Cloud Run-Dienstes generiert wird.

Darüber hinaus gibt der Parameter path in der OpenAPI-Spezifikation den Endpunkt oder die Ressource an, die von der API unterstützt wird. Sie können einen absoluten Pfad angeben oder einen Pfad mit Pfadparametern:

Pfad	Pfad mit Parametern
paths: /hello:	paths: /hello/{name}:

Back-End-Dienst-URL aus einer API-Anfrage generieren

Da API Gateway eine Anfrage vom API-Client verarbeitet, wandelt es die vom API-Client gesendete Anfrage-URL in die URL um, mit der die Anfrage an den Back-End-Dienst gestellt wurde. Wie diese Übersetzung genau stattfindet, hängt von der verwendeten Strategie zur Pfadübersetzung ab.

Die Option path_translation für die Erweiterung x-google-backend unterstützt zwei Strategien zur Pfadübersetzung:

APPEND_PATH_TO_ADDRESS: Die Back-End-Dienst-URL wird generiert, indem der Ressourcenpfad von der Clientanfrage an die address-URL der Erweiterung x-google-backend angehängt wird.

Die meisten Back-End-Dienste verwenden APPEND_PATH_TO_ADDRESS, da das Back-End denselben Ressourcenpfad empfängt, der vom API-Client angegeben wird.
CONSTANT_ADDRESS: Die Back-End-Dienst-URL ist konstant, wie durch die URL address der Erweiterung x-google-backend definiert. Wenn die Clientanfrage einen Ressourcenpfad enthält, wird der Ressourcenpfad mithilfe von Abfrageparametern der URL des Back-End-Dienstes hinzugefügt.

Diese Methode wird normalerweise von Cloud Functions verwendet.

Beispiel:

APPEND_PATH_TO_ADDRESS
- address: https://PROJECT_ID.appspot.com
- Ohne OpenAPI-Pfadparameter:
  - OpenAPI-Pfad: /hello
  - Ressourcenpfad der API-Clientanfrage: /hello
  - Anfrage-URL für Back-End-Dienst: https://PROJECT_ID.appspot.com/hello
- Mit OpenAPI-Pfadparametern:
  - OpenAPI-Pfad: /hello/{name}
  - Ressourcenpfad der API-Clientanfrage: /hello/Dave
  - Anfrage-URL für Back-End-Dienst: https://PROJECT_ID.appspot.com/hello/Dave
CONSTANT_ADDRESS
- address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- Ohne OpenAPI-Pfadparameter
  - OpenAPI-Pfad: /hello
  - Ressourcenpfad der API-Clientanfrage: /hello
  - Anfrage-URL für Back-End-Dienst: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- Mit OpenAPI-Pfadparametern
  - OpenAPI-Pfad: /hello/{name}
  - Ressourcenpfad der API-Clientanfrage: /hello/Dave
  - Anfrage-URL für Back-End-Dienst: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Einstellen von `path_translation`

Legen Sie path_translation als Teil der Einstellung x-google-backend fest:

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]`

Der Standardwert von path_translation hängt davon ab, wo Sie x-google-backend in Ihrer OpenAPI-Spezifikation festgelegt haben:

Wenn x-google-backend auf der obersten Ebene der OpenAPI-Spezifikation verwendet wird, ist path_translation standardmäßig auf APPEND_PATH_TO_ADDRESS festgelegt.
Wenn x-google-backend auf der Vorgangsebene der OpenAPI-Spezifikation verwendet wird, ist path_translation standardmäßig auf CONSTANT_ADDRESS gesetzt.