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 alcune 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 nella 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	Uno dei seguenti: x-google-backend: address: `APP_URL` x-google-backend: address: `DETERMINISTIC_URL`
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

Uno dei seguenti:

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

x-google-backend:
  address: DETERMINISTIC_URL

Ambiente standard di App Engine

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

In questi esempi:

APP_URL specifica l'URL effettivo del tuo servizio Cloud Run (il percorso completo dell'API chiamata), noto anche come URL non deterministico. Ad esempio https://hello-abc1def2gh-uc.a.run.app.
DETERMINISTIC_URL è l'URL deterministico per il backend del servizio Cloud Run.

Nota: se prevedi di utilizzare l'URL deterministico per controllare le versioni del backend del servizio Cloud Run, devi specificare uno dei seguenti elementi:

Open API 2.0: campo jwt_audience in address nella sezione x-google-backend
Open API 3.0: campo jwtAudience in address nella sezione x-google-api-management

Il valore del campo jwt_audience o jwtAudience deve essere l'hostname del servizio Cloud Run. Ad esempio, per OpenAPI 2.0:

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

Se il campo jwt_audience o jwtAudience non è presente, il campo viene impostato sul valore del campo address per l'attestazione del pubblico JWT. Ciò può comportare un'attestazione del pubblico JWT imprevista per Cloud Run se l'URL del tag di revisione viene utilizzato per address e non viene specificato alcun jwt_audience o jwtAudience.

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. La modalità esatta di 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 parametri di ricerca.

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 di `path_translation`

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