Daten an den und von dem Backend-Dienst übergeben

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

Anfrageheader
Abfrageparameter
Formulardaten
XML- oder JSON-Nutzlasten
Anfragepfade

Bei der Erstellung der Antwort auf die API-Anfrage kann der Backend-Dienst Daten an den API-Client zurückgeben, darunter:

Antwortheader
XML- oder JSON-Nutzlasten

In diesem Dokument wird beschrieben, wie diese Daten an den und vom 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 Backend-Dienst übergeben. Der Backend-Dienst muss die Anfragedaten dann im Rahmen der Bearbeitung der Anfrage parsen.

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

Alle Daten, die in der Antwort vom Backend-Dienst empfangen werden, werden unverändert an den API-Client übergeben. 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, 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 Backend-Dienst-URL beschrieben.

Back-End-Dienstadresse und -Pfad in der OpenAPI-Spezifikation festlegen

In der OpenAPI-Spezifikation, die Sie zum Erstellen einer API-Konfiguration verwenden, geben Sie mit der Erweiterung x-google-backend die URL des Backend-Dienstes an. Sie geben den Backend-Dienst beispielsweise so an:

Backend	x-google-backend
Cloud Run-Funktionen	x-google-backend: address: https://`GCP_REGION`-`PROJECT_ID`.cloudfunctions.net/hello
Cloud Run	Einer der folgenden: x-google-backend: address: `APP_URL` x-google-backend: address: `DETERMINISTIC_URL`
App Engine-Standardumgebung	x-google-backend: address: https://`PROJECT_ID`.appspot.com

Backend

x-google-backend

Cloud Run-Funktionen

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

Cloud Run

Einer der folgenden:

```
x-google-backend:
  address: APP_URL
```

x-google-backend:
  address: DETERMINISTIC_URL

App Engine-Standardumgebung

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

In diesen Beispielen gilt Folgendes:

APP_URL gibt die tatsächliche URL Ihres Cloud Run-Dienstes an (den vollständigen Pfad der aufgerufenen API), auch als nicht deterministische URL bezeichnet. Beispiel: https://hello-abc1def2gh-uc.a.run.app.
DETERMINISTIC_URL ist die deterministische URL für Ihr Cloud Run-Dienst-Backend.

Hinweis: Wenn Sie die deterministische URL verwenden möchten, um Versionen Ihres Cloud Run-Dienst-Back-Ends zu erstellen, müssen Sie eines der folgenden Elemente angeben:

Open API 2.0: Feld jwt_audience unter address im Abschnitt x-google-backend
Open API 3.0: Feld jwtAudience unter address im Abschnitt x-google-api-management

Der Wert des Felds jwt_audience oder jwtAudience sollte der Hostname des Cloud Run-Dienstes sein. Beispiel für OpenAPI 2.0:

...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...

Wenn das Feld jwt_audience oder jwtAudience nicht vorhanden ist, wird standardmäßig der Wert des Felds address für die JWT-Zielgruppenanforderung verwendet. Dies kann zu einem unerwarteten JWT-Zielgruppenanspruch für Cloud Run führen, wenn die Überarbeitungs-Tag-URL für address verwendet wird und kein jwt_audience oder jwtAudience angegeben ist.

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

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

Backend-Dienst-URL aus einer API-Anfrage generieren

Wenn API Gateway eine Anfrage vom API-Client verarbeitet, wird die vom API-Client gesendete Anfrage-URL in die URL übersetzt, die für die 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 Backend-Dienste verwenden APPEND_PATH_TO_ADDRESS, da das Backend dadurch denselben Ressourcenpfad wie vom API-Client angegeben empfängt.
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 der Back-End-Dienst-URL mithilfe von Abfrageparametern hinzugefügt.

Diese Methode wird in der Regel von Cloud Run-Funktionen verwendet.

Beispiel:

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

Einstellen von `path_translation`

Legen Sie path_translation als Teil der Festlegung 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 CONSTANT_ADDRESS der Standardwert für path_translation.