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.

In questa pagina vengono descritte 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. Inserisci questa estensione nella directory principale 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 del modello.
mcp MCP o bool No Vuoto Abilitare o configurare le funzionalità del Model Context Protocol (MCP).

Metric oggetto

L'oggetto Metric definisce una metrica utilizzata per l'applicazione delle quote.

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.

QuotaLimit 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 creerà il token ID dell'istanza con un pubblico JWT che corrisponde al campo dell'indirizzo. La specifica manuale di jwt_audience è obbligatoria 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 Impedire al proxy del piano dati 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 più alto e non viene specificato path_translation, il valore predefinito di pathTranslation è APPEND_PATH_TO_ADDRESS. Quando x-google-backend è impostato su on 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 da una richiesta. Le risposte che superano questa scadenza vanno in timeout. Su un endpoint SSE o con trasferimento in blocchi, la scadenza limita comunque la durata dell'intero stream; su un endpoint gRPC o WebSocket, invece, limita l'intervallo tra i messaggi. Consulta Imposta la scadenza dello stream per i timeout che si applicano a ogni tipo di richiesta. Ometti il campo o impostalo su 0 per utilizzare il valore predefinito. Un valore negativo viene rifiutato. La scadenza è configurabile fino a 3600 secondi. Un gateway non in streaming applica un valore massimo inferiore di 600 secondi, rifiutando una scadenza più elevata al momento della creazione o dell'aggiornamento del gateway anziché al momento della creazione della configurazione API.
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. I requisiti del protocollo dipendono dal tipo di streaming:
- gRPC: devi impostare il protocollo su h2.
- WebSockets: devi utilizzare http/1.1.
- Eventi inviati dal server (SSE) e distribuzione incrementale delle risposte: puoi utilizzare http/1.1 o h2. Per un rendimento migliore, ti consigliamo di utilizzare h2.

AI oggetto

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

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 i router e le regole di routing del modello.

La tabella seguente descrive i campi per Routing:

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

Router oggetto

L'oggetto Router definisce un router del modello 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 a nessuna regola esplicita.
rules [Rule] No Vuoto Elenco di regole di routing del modello esplicite.

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 i percorsi 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 provider e viene restituito nel campo model della risposta.

MCP oggetto

L'oggetto MCP configura le funzionalità del Model Context Protocol (MCP) per il tuo servizio. Puoi impostare mcp su un valore booleano o su un oggetto. Imposta su true per attivare l'MCP a livello globale per tutte le operazioni idonee con le impostazioni predefinite.

La tabella seguente descrive i campi dell'oggetto MCP:

Campo Tipo Obbligatorio Predefinito Descrizione
tools-list ToolsList No Vuoto Configura le impostazioni per il metodo MCP tools/list.

ToolsList oggetto

L'oggetto ToolsList configura le impostazioni per il metodo MCP tools/list.

La tabella seguente descrive i campi per ToolsList:

Campo Tipo Obbligatorio Predefinito Descrizione
security map No Vuoto Abilita l'autenticazione su tools/list. Come best practice per la sicurezza, ti consigliamo vivamente di configurare questa opzione. Deve denominare esattamente uno schema di sicurezza della chiave API o JWT definito in components.securitySchemes.

x-google-auth

Facoltativo.

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

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 provider 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 con codifica base64url.
audiences [string] No Vuoto Elenca i segmenti di pubblico che il campo JWT aud deve corrispondere 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 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 di 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 corrisponde al nome di un backend definito in x-google-api-management.backends. Devi impostare questa estensione per API Gateway. Puoi definire questa estensione al livello più alto del documento OpenAPI o per una singola operazione per eseguire l'override del 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 del modello definito in x-google-api-management.ai.models.routing.routers. Se utilizzato, il suo valore deve essere una stringa che corrisponde al nome di un router definito in x-google-api-management.ai.models.routing.routers.

Questa estensione è supportata solo nelle specifiche OpenAPI 3.x; 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 sia x-google-backend nella stessa operazione, né puoi combinare operazioni di routing del modello e non di routing del modello in percorsi diversi all'interno della stessa specifica API. Inoltre, non puoi utilizzare il routing del modello insieme al Model Context Protocol (MCP); l'attivazione di x-google-api-management.mcp rende questa estensione non disponibile.

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

Facoltativo.

L'estensione x-google-mcp-tool viene utilizzata su singole operazioni per esporle come strumenti MCP e, facoltativamente, eseguire l'override del nome e della descrizione dello strumento generati.

Questa estensione è supportata solo nelle specifiche OpenAPI 3.x; non può essere utilizzata con le specifiche OpenAPI 2.0 (Swagger). Puoi definire questa estensione solo a livello di singola operazione.

Accetta un valore booleano o un oggetto.

  • true Imposta su false per disattivarlo, eseguendo l'override di un'attivazione globale.
  • Modulo oggetto: attiva e sostituisci le impostazioni dello strumento generate.

La tabella seguente descrive i campi di x-google-mcp-tool quando viene utilizzato come oggetto:

Campo Tipo Obbligatorio Predefinito Descrizione
name string No operationId dell'operazione Il nome dello strumento MCP. Deve corrispondere a [A-Za-z0-9_.-]{1,128} ed essere univoco nella specifica.
description string No La descrizione dell'operazione, con fallback al riepilogo La descrizione dello strumento MCP. Questo è l'indicatore principale utilizzato da un LLM per la selezione degli strumenti.

Ad esempio:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

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 di risorse multiorigine (CORS) impostando la proprietà allowCors su true.

  • Percorso di base: il percorso di base impostato sul server con x-google-endpoint viene utilizzato per l'API. 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 su 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ì Questo valore deve essere impostato su **.

Informazioni sulle limitazioni delle estensioni OpenAPI

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

Passaggi successivi