Trasferimento di dati da e verso il servizio di backend

Quando un client API invia una richiesta all'API di cui è stato eseguito il deployment in API Gateway, il client può trasmettere una o tutte le seguenti informazioni come parte 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.

In che modo vengono passati i dati delle richieste al servizio di backend?

Tutti i dati contenuti nella richiesta dal client API vengono passati senza modifiche al servizio di backend. Spetta quindi al servizio di backend analizzare i dati della richiesta nell'ambito 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 dell'API elaborare eventuali dati restituiti nella risposta.

In che modo viene passato l'URL della richiesta 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 utilizzata per creare una configurazione API, utilizza l'estensione x-google-backend per specificare l'URL del servizio di backend. Ad esempio, specifichi 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://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 al momento della creazione del servizio Cloud Run.

Inoltre, il parametro path nella specifica OpenAPI specifica l'endpoint, o resource, supportate 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 la traduzione dipende dalla strategia di traduzione del percorso che stai utilizzando.

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 token dalla richiesta del client all'URL address di x-google-backend .

  La maggior parte dei servizi di backend utilizza APPEND_PATH_TO_ADDRESS perché significa che il backend riceve lo stesso percorso di 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 è in genere utilizzato dalle funzioni di 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 risorsa richiesta 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 risorsa richiesta client API: /hello
    • URL della richiesta del 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

Impostazione di path_translation

Imposta path_translation nell'ambito 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.