Estensioni OpenAPI 3.x in API Gateway

API Gateway accetta un insieme di estensioni specifiche di Google alla specifica OpenAPI che configurano i comportamenti del gateway. Queste estensioni ti consentono di specificare le impostazioni di gestione delle API, i metodi di autenticazione, i limiti di quota e le integrazioni di backend direttamente nel documento OpenAPI. Comprendere queste estensioni ti aiuta a personalizzare il comportamento del servizio e a integrarlo con le funzionalità di API Gateway.

Questa pagina descrive le estensioni specifiche di Google alla specifica OpenAPI 3.x.

Sebbene gli esempi forniti siano in formato YAML, è supportato anche JSON.

x-google-api-management

Obbligatorio.

L'estensione x-google-api-management definisce le impostazioni di gestione delle API di primo livello per il tuo servizio. Posiziona questa estensione nella radice del documento OpenAPI.

La tabella seguente descrive i campi per x-google-api-management:

Campo Tipo Obbligatorio Predefinito Descrizione
metrics map[string]Metric No Vuoto Definisci le metriche per applicare i limiti di quota.
quota map[string]Quota No Vuoto Specifica i limiti di quota per il tuo servizio.
backends map[string]Backend Sì Vuoto Configura i servizi di backend.
apiName string No Vuoto Associa un nome alle operazioni definite nel documento OpenAPI.

Metric Oggetto

L'oggetto Metric definisce una metrica utilizzata per l'applicazione della quota.

La tabella seguente descrive i campi per Metric:

Campo Tipo Obbligatorio Predefinito Descrizione
displayName string No Vuoto Nome visualizzato della metrica.

Quota Oggetto

L'oggetto Quota definisce i limiti di quota.

La tabella seguente descrive i campi per Quota:

Campo Tipo Obbligatorio Predefinito Descrizione
limits map[string]QuotaLimit No Vuoto Specifica i limiti di quota.

Quota Limit Oggetto

L'oggetto QuotaLimit definisce un limite di quota specifico.

La tabella seguente descrive i campi per QuotaLimit:

Campo Tipo Obbligatorio Descrizione
metric string Sì Fai riferimento a una metrica dichiarata in questo documento OpenAPI.
values int64 Sì Imposta il valore massimo che la metrica può raggiungere prima che le richieste client vengano rifiutate.

Backend Oggetto

L'oggetto Backend configura un servizio di backend. Devi impostare jwtAudience o disableAuth.

La tabella seguente descrive i campi per Backend:

Campo Tipo Obbligatorio Predefinito Descrizione
address string No Vuoto Specifica l'URL del backend.
jwtAudience string No Vuoto Per impostazione predefinita, API Gateway crea il token ID istanza con un pubblico JWT che corrisponde al campo dell'indirizzo. La specifica manuale di jwt_audience è necessaria solo quando il backend di destinazione utilizza l'autenticazione basata su JWT e il pubblico previsto è diverso dal valore specificato nel campo dell'indirizzo. Per i backend remoti di cui è stato eseguito il deployment su App Engine o con IAP, devi eseguire l'override del pubblico JWT. App Engine e IAP utilizzano il proprio ID client OAuth come pubblico previsto.
disableAuth bool No False Impedisci al proxy del piano di controllo di ottenere un token ID istanza e di allegarlo alla richiesta.
pathTranslation string No APPEND_PATH_TO_ADDRESS o CONSTANT_ADDRESS Imposta la strategia di traduzione del percorso quando esegui il proxy delle richieste al backend di destinazione. Quando x-google-backend è impostato al livello superiore e non è specificato path_translation, il valore predefinito di pathTranslation è APPEND_PATH_TO_ADDRESS. Quando x-google-backend è impostato a livello di operazione e non è specificato path_translation, il valore predefinito è CONSTANT_ADDRESS.
deadline double No 15.0 Specifica il numero di secondi di attesa per una risposta completa a una richiesta. Le risposte che superano questo termine scadono.
protocol string No http/1.1 Imposta il protocollo per l'invio di una richiesta al backend. I valori supportati includono http/1.1 e h2.

x-google-auth

(Facoltativo)

L'estensione x-google-auth definisce le impostazioni di autenticazione all'interno di un oggetto schema di sicurezza.

La tabella seguente descrive i campi per x-google-auth:

Campo Tipo Obbligatorio Predefinito Descrizione
issuer string No Vuoto Specifica l'emittente di una credenziale. I valori possono essere un nome host o un indirizzo email.
jwksUri string No Vuoto

Fornisci l'URI del set di chiavi pubbliche del fornitore per convalidare la firma del token web JSON. API Gateway supporta due formati di chiave pubblica asimmetrica definiti da questa estensione OpenAPI:

  1. Formato del set JWK. Ad esempio: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. X509. Ad esempio: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Se utilizzi un formato di chiave simmetrica, imposta jwksUri sull'URI di un file che contiene la stringa della chiave codificata in base64url.
audiences [string] No Vuoto Elenca i segmenti di pubblico a cui deve corrispondere il campo aud del JWT durante l'autenticazione JWT.
jwtLocations [JwtLocations] No Vuoto Personalizza le posizioni per il token JWT. Per impostazione predefinita, un JWT viene passato nell'intestazione Authorization (con il prefisso "Bearer "), nell'intestazione X-Goog-Iap-Jwt-Assertion o nel parametro di query access_token.

JwtLocations Oggetto

L'oggetto JwtLocations fornisce posizioni personalizzate per il token JWT.

La tabella seguente descrive i campi per JwtLocations:

Campo Tipo Obbligatorio Predefinito Descrizione
header | query string Sì N/D Specifica il nome dell'intestazione contenente il JWT o il nome del parametro di query contenente il JWT.
valuePrefix string No Vuoto Solo per l'intestazione. Se impostato, il suo valore deve corrispondere al prefisso del valore dell'intestazione contenente il JWT.

x-google-quota

(Facoltativo)

L'estensione x-google-quota definisce i limiti di quota. Puoi definire questa estensione a livello di primo livello del documento OpenAPI o per una singola operazione.

La tabella seguente descrive i campi per x-google-quota:

Campo Tipo Obbligatorio Descrizione
self map[string]int64 Sì L'oggetto quota (self) fa riferimento a tutte le metriche definite al suo interno. In questo caso, mappa una metrica (ad esempio read-requests) a un importo per incrementare la metrica. Le richieste vengono rifiutate quando il valore della metrica raggiunge il limite della quota.

x-google-backend

Obbligatorio.

L'estensione x-google-backend fa riferimento a un backend definito in x-google-api-management. Devi impostare questa estensione per API Gateway. Puoi definire questa estensione a livello di primo livello del documento OpenAPI o per una singola operazione.

La tabella seguente descrive i campi per x-google-backend:

Campo Tipo Obbligatorio Descrizione
self string Sì Fai riferimento all'ID di un backend definito in x-google-api-management.

x-google-endpoint

(Facoltativo)

L'estensione x-google-endpoint viene utilizzata per configurare le proprietà di un server definito nell'array servers di un documento OpenAPI 3.x. Solo una voce del server nel documento OpenAPI può utilizzare l'estensione x-google-endpoint.

L'estensione definisce anche altre funzionalità di backend, tra cui:

  • CORS: puoi attivare la condivisione delle risorse tra origini (CORS) impostando la proprietà allowCors su true.

  • Percorso di base: per l'API viene utilizzato il percorso di base impostato sul server con x-google-endpoint. Ad esempio, la seguente configurazione imposta v1 come percorso di base:

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

La tabella seguente descrive i campi per x-google-endpoint:

Campo Tipo Obbligatorio Predefinito Descrizione
allowCors bool No false Consenti le richieste CORS.

x-google-parameter

(Facoltativo)

L'estensione x-google-parameter è definita in un elemento parameter. Può essere utilizzato quando il percorso utilizza i modelli di percorso per specificare che deve essere utilizzato il comportamento di corrispondenza con doppio carattere jolly.

La tabella seguente descrive i campi per x-google-parameter:

Campo Tipo Obbligatorio Descrizione
pattern string Sì Deve essere impostato su **.

Informazioni sulle limitazioni delle estensioni OpenAPI

Queste estensioni OpenAPI hanno limitazioni specifiche. Per saperne di più, consulta Limitazioni delle funzionalità di OpenAPI 3.x.

Passaggi successivi