Trasferimento di dati da e verso il servizio di backend

Quando un client API effettua una richiesta all'API di cui è stato eseguito il deployment in API Gateway, può passare una o tutte le seguenti informazioni come parte della richiesta:

Intestazioni delle richieste
Parametri di query
Dati del modulo
Payload XML o JSON
Percorsi delle richieste

Durante la creazione della risposta alla richiesta API, il servizio di backend può restituire dati al client API, tra cui:

Intestazioni della risposta
Payload XML o JSON

Questo documento descrive come questi dati vengono passati da e verso il servizio di backend.

Come vengono passati i dati delle richieste al servizio di backend?

Tutti i dati contenuti nella richiesta del client API vengono passati senza modifiche al servizio di backend. Spetta quindi al servizio di backend analizzare i dati della richiesta come parte della gestione della richiesta.

Come vengono restituiti i dati di risposta al client API?

Tutti i dati ricevuti nella risposta dal servizio di backend vengono passati senza modifiche al client API. Spetta quindi al client API elaborare i dati restituiti nella risposta.

In che modo l'URL della richiesta viene passato al servizio di backend?

L'URL utilizzato per effettuare una richiesta al servizio di backend è controllato dall'estensione x-google-backend. Questa sezione descrive le opzioni per configurare l'URL del servizio di backend.

Impostazione dell'indirizzo e del percorso del servizio di backend nella specifica OpenAPI

Nella specifica OpenAPI che utilizzi per creare una configurazione API, puoi usare l'estensione x-google-backend per specificare l'URL del servizio di backend. Ad esempio, specifichi il servizio di backend nel formato:

Backend	backend x-google
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
Ambiente standard di App Engine	x-google-backend: address: https://`PROJECT_ID`.appspot.com

Backend

backend x-google

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

Ambiente standard di App Engine


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

In questi esempi:

GCP_REGION specifica la regione Google Cloud per il backend di cui è stato eseguito il deployment.
PROJECT_ID specifica l'ID del progetto Google Cloud.
HASH specifica il codice hash univoco generato al momento della creazione del servizio Cloud Run.

Inoltre, il parametro path nella specifica OpenAPI specifica l'endpoint, o la risorsa, supportato dalla tua API. Puoi specificare un percorso assoluto o uno che utilizza i parametri del percorso:

Percorso	Percorso con parametri
paths: /hello:	paths: /hello/{name}:

Generazione dell'URL del servizio di backend da una richiesta API

Poiché API Gateway gestisce una richiesta dal client API, prende l'URL della richiesta inviato dal client API e lo traduce nell'URL utilizzato per effettuare la richiesta al servizio di backend. Il modo esatto in cui questa traduzione avviene dipende dalla strategia di traduzione del percorso in uso.

L'opzione path_translation dell'estensione x-google-backend supporta due strategie di traduzione del percorso:

APPEND_PATH_TO_ADDRESS: l'URL del servizio di backend viene generato aggiungendo il percorso della risorsa dalla richiesta del client all'URL address dell'estensione x-google-backend.

La maggior parte dei servizi di backend utilizza APPEND_PATH_TO_ADDRESS perché significa che il backend riceve lo stesso percorso della risorsa specificato dal client API.
CONSTANT_ADDRESS: l'URL del servizio di backend è costante, come definito dall'URL address dell'estensione x-google-backend. Se la richiesta del client contiene un percorso della risorsa, questo viene aggiunto all'URL del servizio di backend utilizzando parametri di ricerca.

Questo metodo è generalmente utilizzato da Cloud Functions.

Ad esempio:

APPEND_PATH_TO_ADDRESS
- address: https://PROJECT_ID.appspot.com
- Senza parametri del percorso OpenAPI:
  - Percorso OpenAPI: /hello
  - Percorso risorsa richiesta client API: /hello
  - URL della richiesta di servizio di backend: https://PROJECT_ID.appspot.com/hello
- Con i parametri del percorso OpenAPI:
  - Percorso OpenAPI: /hello/{name}
  - Percorso risorsa richiesta client API: /hello/Dave
  - URL della richiesta di servizio di backend: https://PROJECT_ID.appspot.com/hello/Dave
CONSTANT_ADDRESS
- address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- Senza parametri del percorso OpenAPI
  - Percorso OpenAPI: /hello
  - Percorso risorsa richiesta client API: /hello
  - URL della richiesta di servizio di backend: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- Con i parametri del percorso OpenAPI
  - Percorso OpenAPI: /hello/{name}
  - Percorso risorsa richiesta client API: /hello/Dave
  - URL della richiesta di servizio di backend: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Configurazione di `path_translation`

Imposta path_translation come parte dell'impostazione x-google-backend:

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

Il valore predefinito di path_translation dipende da dove imposti x-google-backend nella specifica OpenAPI:

Quando x-google-backend viene utilizzato al livello superiore della specifica OpenAPI, il valore predefinito di path_translation è APPEND_PATH_TO_ADDRESS.
Quando x-google-backend viene utilizzato a livello di operazione nella specifica OpenAPI, il valore predefinito di path_translation è CONSTANT_ADDRESS.