Daten an den und von dem Back-End-Dienst übergeben

Wenn ein API-Client eine Anfrage an Ihre auf API Gateway bereitgestellte API sendet, kann der Client eine oder alle der folgenden Informationen als Teil der Anfrage übergeben:

  • Anfrageheader
  • Abfrageparameter
  • Formulardaten
  • XML- oder JSON-Nutzlasten
  • Anfragepfade

Beim Erstellen seiner Antwort auf die API-Anfrage kann der Back-End-Dienst Daten an den API-Client zurückgeben, einschließlich:

  • 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 Back-End-Dienst übergeben?

Alle Daten in der Anfrage vom API-Client werden unverändert an den Back-End-Dienst übergeben. Anschließend kann der Back-End-Dienst die Anfragedaten im Rahmen der Verarbeitung der Anfrage 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. Anschließend kann der API-Client alle zurückgegebenen Daten in der Antwort verarbeiten.

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

Die URL, die zum Senden einer 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. Geben Sie beispielsweise den Back-End-Dienst in folgendem Format an:

Back-End 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:

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

Darüber hinaus gibt der Parameter path in der OpenAPI-Spezifikation den von Ihrer API unterstützten Endpunkt bzw. die Ressource an. Sie können einen absoluten oder einen Pfad angeben, der Pfadparameter verwendet:

Pfad Pfad mit Parametern

paths:
  /hello:

paths:
  /hello/{name}:

URL des Back-End-Dienstes aus einer API-Anfrage generieren

Da API Gateway eine Anfrage vom API-Client verarbeitet, wird die vom API-Client gesendete Anfrage-URL in die URL übersetzt, die zum Senden der Anfrage an den Back-End-Dienst verwendet wird. Wie diese Übersetzung erfolgt, hängt davon ab, welche <Strategie für die Pfadübersetzung Sie verwenden.

Die Option path_translation für die 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 URL address der Erweiterung x-google-backend angehängt wird.

    Die meisten Back-End-Dienste verwenden APPEND_PATH_TO_ADDRESS, da das Back-End denselben Ressourcenpfad erhält, wie vom API-Client angegeben.

  • CONSTANT_ADDRESS: Die Back-End-Dienst-URL 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 Functions verwendet.

Beispiel:

  • APPEND_PATH_TO_ADDRESS
    • address: https://PROJECT_ID.appspot.com
    • Ohne OpenAPI-Pfadparameter
      • OpenAPI-Pfad: /hello
      • Ressourcenpfad der API-Clientanfrage: /hello
      • URL für Back-End-Dienstanfrage: https://PROJECT_ID.appspot.com/hello
    • Mit OpenAPI-Pfadparameter
      • OpenAPI-Pfad: /hello/{name}
      • Ressourcenpfad der API-Clientanfrage: /hello/Dave
      • URL für Back-End-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
      • Ressourcenpfad der API-Clientanfrage: /hello
      • URL für Back-End-Dienstanfrage: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
    • Mit OpenAPI-Pfadparametern
      • OpenAPI-Pfad: /hello/{name}
      • Ressourcenpfad der API-Clientanfrage: /hello/Dave
      • URL für Back-End-Dienstanfrage: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Einstellen von path_translation

Legen Sie path_translation als Teil der x-google-backend-Einstellung 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 standardmäßig APPEND_PATH_TO_ADDRESS.

  • Wenn x-google-backend auf der Vorgangsebene der OpenAPI-Spezifikation verwendet wird, ist path_translation standardmäßig CONSTANT_ADDRESS.