Daten an den und von dem Backend-Dienst übergeben

Wenn ein API-Client eine Anfrage an Ihre API sendet, die in API Gateway bereitgestellt wird, 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 Daten zurückgeben an den API-Client gesendet, einschließlich:

• Antwortheader
• XML- oder JSON-Nutzlasten

In diesem Dokument wird beschrieben, wie diese Daten an den und von dem Backend-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. Es liegt dann am Backend-Dienst, die Anfragedaten im Rahmen der Anfragebearbeitung zu parsen.

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

Alle in der Antwort vom Back-End-Dienst empfangenen Daten werden übergeben. unverändert zum API-Client. Es liegt dann am API-Client, alle zurückgegebenen Daten in der Antwort zu verarbeiten.

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

Die URL, über die eine Anfrage an den Back-End-Dienst gesendet 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, mit der Sie eine API-Konfiguration erstellen, geben Sie mit der Erweiterung x-google-backend die URL des Back-End-Dienstes an. Beispielsweise geben Sie den Back-End-Dienst im folgenden Format an:

Backend	x-google-backend
Cloud Run-Funktionen	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:

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

Außerdem gibt der Parameter path in der OpenAPI-Spezifikation den Endpunkt oder die Ressource an, die von Ihrer API unterstützt wird. Sie können einen absoluten Pfad oder einen Pfad angeben, der Pfadparameter:

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

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

Wenn API Gateway eine Anfrage vom API-Client verarbeitet, nimmt es die vom API-Client gesendete Anfrage-URL und übersetzt sie in die URL, die für die Anfrage an den Back-End-Dienst verwendet wird. Die genaue Funktionsweise dieser Übersetzung hängt davon ab, welche Strategie für die Pfadübersetzung Sie verwenden.

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

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

  Die meisten Backend-Dienste verwenden APPEND_PATH_TO_ADDRESS, da das Backend dann denselben Ressourcenpfad empfängt, der vom API-Client angegeben wurde.

• CONSTANT_ADDRESS: Die URL des Backend-Dienstes bleibt gemäß der URL address der Erweiterung x-google-backend unverändert. Wenn die Clientanfrage einen Ressourcenpfad enthält, wird der Ressourcenpfad mithilfe von Abfrageparametern zur Back-End-Dienst-URL hinzugefügt.

  Diese Methode wird normalerweise von Cloud Run-Funktionen verwendet.

Beispiel:

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

Einstellen von path_translation

Legen Sie path_translation im Rahmen der Einrichtung von 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 festlegen:

• Wenn x-google-backend auf der obersten Ebene der OpenAPI-Spezifikation verwendet wird, ist path_translation der Standardwert für APPEND_PATH_TO_ADDRESS.

• Wenn x-google-backend auf der Vorgangsebene der OpenAPI-Spezifikation verwendet wird, ist path_translation der Standardwert für CONSTANT_ADDRESS.