Trasferimento di dati da e verso il servizio di backend

Quando un client API effettua una richiesta alla tua API di cui è stato eseguito il deployment su API Gateway, il client può trasmettere una o tutte le seguenti informazioni nell'ambito della richiesta:

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

Nella 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 trasferiti da e verso il servizio di backend.

Come vengono passati i dati della richiesta al servizio di backend?

Tutti i dati della richiesta dal client API vengono passati invariati al servizio di backend. Spetta quindi al servizio di backend analizzare i dati della richiesta nell'ambito della gestione della richiesta.

In che modo i dati di risposta vengono restituiti al client API?

Tutti i dati ricevuti nella risposta dal servizio di backend vengono passati invariati 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, utilizzi l'estensione x-google-backend per specificare l'URL del servizio di backend. Ad esempio, specifica il servizio di backend nel formato:

Backend	x-google-backend
Cloud Run Functions	x-google-backend: address: https://`GCP_REGION`-`PROJECT_ID`.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://[`TAG`---]`SERVICE_NAME`-`PROJECT_NUMBER`.`REGION`.run.app
Ambiente standard di App Engine	x-google-backend: address: https://`PROJECT_ID`.appspot.com

Backend

x-google-backend

Cloud Run Functions

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

Cloud Run

x-google-backend:
  address: https://[TAG---]SERVICE_NAME-PROJECT_NUMBER.REGION.run.app

Ambiente standard di App Engine

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

In questi esempi:

GCP_REGION specifica la Google Cloud regione per il backend di cui è stato eseguito il deployment.
PROJECT_ID specifica l' Google Cloud ID progetto.
TAG è il tag di traffico facoltativo per la revisione di Cloud Run che stai richiedendo. Vedi anche URL deterministico nella documentazione di Cloud Run.
SERVICE_NAME è il nome del servizio Cloud Run.
PROJECT_NUMBER è il Google Cloud numero di progetto.
REGION è il nome della regione, ad esempio us-west1.

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

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

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

Quando 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 avviene questa traduzione dipende dalla strategia di traduzione dei percorsi che utilizzi.

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

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é 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 client contiene un percorso della risorsa, il percorso della risorsa viene aggiunto all'URL del servizio di backend utilizzando i parametri di query.

Questo metodo viene in genere utilizzato da Cloud Run Functions.

Ad esempio:

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

Impostazione `path_translation`

Imposta path_translation come parte dell'impostazione di 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, path_translation viene impostato su APPEND_PATH_TO_ADDRESS per impostazione predefinita.
Quando x-google-backend viene utilizzato a livello di operazione della specifica OpenAPI, path_translation viene impostato per impostazione predefinita su CONSTANT_ADDRESS.