Trasferimento di dati da e verso il servizio di backend

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

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

Durante la creazione della risposta alla richiesta dell'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 trasmessi al servizio di backend e da questo.

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

Tutti i dati nella richiesta del client API vengono trasmessi 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 dell'API?

Tutti i dati ricevuti nella risposta dal servizio di backend vengono trasmessi immutati al client API. Spetta quindi al client dell'API elaborare eventuali 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.

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

Nella specifica OpenAPI utilizzata per creare una configurazione API, utilizza 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
Funzioni Cloud Run	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:

1. GCP_REGION specifica la regione Google Cloud per il backend di cui è stato eseguito il deployment.
2. PROJECT_ID specifica l'ID progetto Google Cloud.
3. HASH specifica il codice hash univoco generato quando viene creato il servizio Cloud Run.

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 in cui avviene questa traduzione dipende dalla strategia di traduzione dei percorsi utilizzata.

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é indica 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, il percorso della risorsa viene aggiunto all'URL del servizio di backend utilizzando parametri di ricerca.

  Questo metodo viene in genere utilizzato dalle funzioni Cloud Run.

Ad esempio:

• APPEND_PATH_TO_ADDRESS
  • address: https://PROJECT_ID.appspot.com
  • Senza parametri del percorso OpenAPI:
    • Percorso OpenAPI: /hello
    • Percorso della risorsa richiesta dal 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 della risorsa richiesta dal 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 di percorso OpenAPI
    • Percorso OpenAPI: /hello
    • Percorso della risorsa richiesta dal 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 della risorsa richiesta dal 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 in corso…

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,path_translation assume per impostazione predefinita il valore APPEND_PATH_TO_ADDRESS.

• Quando x-google-backend viene utilizzato a livello di operazione della specifica OpenAPI,path_translation assume per impostazione predefinita il valore CONSTANT_ADDRESS.