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 |
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'URLaddress
dell'estensionex-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'URLaddress
dell'estensionex-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
- Percorso OpenAPI:
- 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
- Percorso OpenAPI:
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
- Percorso OpenAPI:
- 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
- Percorso OpenAPI:
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 dipath_translation
èAPPEND_PATH_TO_ADDRESS
.Quando
x-google-backend
viene utilizzato a livello di operazione nella specifica OpenAPI, il valore predefinito dipath_translation
èCONSTANT_ADDRESS
.