Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Trasferisci i 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ò passare alcune o tutte le seguenti informazioni nell'ambito della richiesta:

Intestazioni delle richieste
Parametri di query
Dati 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 trasferiti da e verso il servizio di backend.

In che modo i dati della richiesta vengono trasmessi al servizio di backend?

Tutti i dati della richiesta del client API vengono passati invariati al servizio di backend. Spetta poi 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 trasmessi invariati al client API. Spetta poi 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 la configurazione dell'URL del servizio di backend.

Imposta l'indirizzo e il 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 seguente 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 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 App Engine

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

In questi esempi:

APP_URL specifica l'URL effettivo del 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 il controllo delle versioni del backend del servizio Cloud Run, devi specificare una delle seguenti opzioni:

OpenAPI 2.0: campo jwt_audience insieme a address nella sezione x-google-backend
OpenAPI 3.x: campo jwtAudience insieme a address nella definizione del backend in x-google-api-management.backends

Imposta il campo jwt_audience o jwtAudience sul nome host 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 assume il valore predefinito del campo address per la richiesta di 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 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 un percorso che utilizza parametri di percorso:

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

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

Imposta `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 più alto 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 su CONSTANT_ADDRESS per impostazione predefinita.