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. La comprensione di 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.
ai AI No Vuoto Configura le funzionalità di intelligenza artificiale, incluso il routing dei modelli.

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.

Backends Oggetto

Obbligatorio.

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

La tabella seguente descrive i campi per Backends:

Campo Tipo Obbligatorio Predefinito Descrizione
address string Sì 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 data plane 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 conversione 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 da attendere per una risposta completa a una richiesta. Le risposte che superano questo termine vanno in timeout. Il limite massimo della scadenza è 600 secondi.
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.

AI Oggetto

L'oggetto AI configura le funzionalità di intelligenza artificiale per il tuo servizio, ad esempio il routing dei modelli.

La tabella seguente descrive i campi per AI:

Campo Tipo Obbligatorio Predefinito Descrizione
models Models No Vuoto Configura le integrazioni dei modelli di AI.

Models Oggetto

L'oggetto Models definisce le configurazioni specifiche del modello.

La tabella seguente descrive i campi per Models:

Campo Tipo Obbligatorio Predefinito Descrizione
routing Routing No Vuoto Configura le impostazioni di routing del modello.

Routing Oggetto

L'oggetto Routing definisce le regole di routing e i router del modello.

La tabella seguente descrive i campi per Routing:

Campo Tipo Obbligatorio Predefinito Descrizione
routers map[string]Router No Vuoto Definisci i router del modello denominati.

Router Oggetto

L'oggetto Router definisce un router di modelli denominato.

La tabella seguente descrive i campi per Router:

Campo Tipo Obbligatorio Predefinito Descrizione
defaultModel DefaultModel Sì Vuoto La destinazione del modello di riserva obbligatoria utilizzata quando una richiesta in entrata non corrisponde ad alcuna regola esplicita.
rules [Rule] No Vuoto Elenco delle regole di routing esplicite del modello.

DefaultModel Oggetto

L'oggetto DefaultModel specifica la destinazione di riserva.

La tabella seguente descrive i campi per DefaultModel:

Campo Tipo Obbligatorio Predefinito Descrizione
backend string Sì Vuoto Fai riferimento a un backend dichiarato in x-google-api-management.backends.
targetModel string Sì Vuoto Specifica l'identificatore del modello di destinazione nel formato <provider>/<model-id>. Per le route compatibili con OpenAI, questo valore viene inoltrato come attributo model in uscita nel corpo della richiesta quando si verifica il fallback.

Rule Oggetto

L'oggetto Rule definisce una regola di routing del modello esplicita.

La tabella seguente descrive i campi per Rule:

Campo Tipo Obbligatorio Predefinito Descrizione
model string Sì Vuoto La stringa in entrata corrisponde all'attributo model nel payload JSON del client. Per le route compatibili con OpenAI, questa stringa viene inoltrata come attributo model in uscita nel corpo della richiesta e deve essere una stringa <provider>/<model-id> valida.
backend string Sì Vuoto Fai riferimento a un backend dichiarato in x-google-api-management.backends.
targetModel string Sì Vuoto Specifica l'identificatore del modello di destinazione nel formato <provider>/<model-id>. Questo valore seleziona la traduzione del fornitore e viene restituito nel campo model della risposta.

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 viene utilizzata nelle singole operazioni per specificare quali metriche definite in x-google-api-management.metrics sono interessate dalle richieste a quell'operazione.

x-google-quota è un oggetto contenente coppie chiave-valore, in cui ogni chiave è un nome della metrica e il valore è il costo intero per ogni richiesta all'operazione. Ad esempio:

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

x-google-backend

Obbligatorio.

L'estensione x-google-backend fa riferimento a un backend definito in x-google-api-management.backends. Se utilizzato, il suo valore deve essere una stringa che corrisponda al nome di un backend definito in x-google-api-management.backends. Devi impostare questa estensione per API Gateway. Puoi definire questa estensione a livello di primo livello del documento OpenAPI o per un' operazione individuale per sostituire il backend di primo livello.

Ad esempio:

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

x-google-model-router

Facoltativo.

L'estensione x-google-model-router fa riferimento a un router di modelli definito in x-google-api-management.ai.models.routing.routers. Se utilizzato, il suo valore deve essere una stringa corrispondente al nome di un router definito in x-google-api-management.ai.models.routing.routers.

Questa estensione è supportata solo nelle specifiche OpenAPI 3.x e non può essere utilizzata con le specifiche OpenAPI 2.0 (Swagger). Puoi definire questa estensione solo a livello di singola operazione per le operazioni che utilizzano il metodo HTTP POST. Non puoi specificare sia x-google-model-router che x-google-backend nella stessa operazione, né puoi combinare operazioni di routing dei modelli e non dei modelli in percorsi diversi all'interno della stessa specifica API.

Ad esempio:

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

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 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