Estensioni OpenAPI 2.0 in API Gateway

API Gateway accetta un insieme di estensioni specifiche di Google alla specifica OpenAPI che configurano i comportamenti del gateway. In questa pagina vengono descritte le estensioni personalizzate specifiche di Google della specifica OpenAPI 2.0 utilizzate per configurare i comportamenti di API Gateway, come il routing del backend, l'autenticazione e le funzionalità di gestione delle API.

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

Convenzione di denominazione

I nomi delle estensioni Google OpenAPI iniziano con il prefisso x-google-.

x-google-allow

x-google-allow: [configured | all]

Questa estensione viene utilizzata al livello più alto di una specifica OpenAPI per indicare quali percorsi dell'URL devono essere consentiti tramite API Gateway.

I valori possibili sono configured e all.

Il valore predefinito è configured, il che significa che solo i metodi API elencati nella specifica OpenAPI vengono gestiti tramite API Gateway.

Quando viene utilizzato all, le chiamate non configurate, con o senza una chiave API o l'autenticazione utente, passano attraverso API Gateway alla tua API.

API Gateway elabora le chiamate alla tua API in modo sensibile alle maiuscole. Ad esempio, API Gateway considera /widgets e /Widgets come metodi API diversi.

Quando utilizzi all, devi prestare particolare attenzione a due aree:

  • Qualsiasi chiave API o regola di autenticazione.
  • Il routing del percorso di backend nel tuo servizio.

Come best practice, ti consigliamo di configurare l'API in modo che utilizzi il routing dei percorsi sensibile alle maiuscole. Se utilizzi il routing sensibile alle maiuscole, l'API restituisce un codice di stato HTTP 404 quando il metodo richiesto nell'URL non corrisponde al nome del metodo API elencato nella specifica OpenAPI. Tieni presente che i framework di applicazioni web come Node.js Express hanno un'impostazione per attivare o disattivare il routing sensibile alle maiuscole. Il comportamento predefinito dipende dal framework che utilizzi. Ti consigliamo di rivedere le impostazioni nel tuo framework per assicurarti che il routing sensibile alle maiuscole sia abilitato. Questo suggerimento è in linea con la specifica OpenAPI v2.0, che afferma: "Tutti i nomi dei campi nella specifica sono sensibili alle maiuscole".

Esempio

Supponiamo che:

  • x-google-allow è impostato su all.
  • Il metodo API widgets è elencato nella specifica OpenAPI, ma non Widgets.
  • Hai configurato la specifica OpenAPI in modo che richieda una chiave API.

Poiché widgets è elencato nella specifica OpenAPI, API Gateway blocca la seguente richiesta perché non ha una chiave API:

https://my-project-id.appspot.com/widgets

Poiché Widgets non è elencato nella specifica OpenAPI, API Gateway trasmette la seguente richiesta al tuo servizio senza una chiave API:

https://my-project-id.appspot.com/Widgets/

Se l'API utilizza il routing sensibile alle maiuscole (e non hai indirizzato le chiamate a "Widgets" a nessun codice), il backend dell'API restituisce un errore 404. Tuttavia, se utilizzi il routing senza distinzione tra maiuscole e minuscole, il backend dell'API indirizza questa chiamata a "widgets".

Linguaggi e framework diversi hanno metodi diversi per controllare la sensibilità alle maiuscole e il routing. Per maggiori dettagli, consulta la documentazione del tuo framework.

x-google-backend

L'estensione x-google-backend specifica come instradare le richieste ai backend remoti. L'estensione può essere specificata a livello superiore, a livello di operazione o a entrambi i livelli di una specifica OpenAPI.

L'estensione x-google-backend può anche configurare altre impostazioni per i backend remoti, come l'autenticazione e i timeout. Tutte queste configurazioni possono essere applicate per singola operazione.

L'estensione x-google-backend contiene i seguenti campi:

address

address: URL

Obbligatorio. L'URL del backend di destinazione. Lo schema dell'indirizzo deve essere http o https.

Quando il routing viene eseguito verso backend remoti (serverless), l'indirizzo deve essere impostato e la parte dello schema deve essere https.

jwt_audience | disable_auth

Deve essere impostata solo una di queste due proprietà.

Se un'operazione utilizza x-google-backend, ma non specifica jwt_audience o disable_auth, API Gateway imposterà automaticamente jwt_audience in modo che corrisponda a address. Se address non è impostato, API Gateway imposterà automaticamente disable_auth su true.

jwt_audience

jwt_audience: string

Facoltativo. Il pubblico JWT specificato quando API Gateway ottiene un token ID istanza, che viene poi utilizzato per effettuare la richiesta al backend di destinazione.

Quando configuri API Gateway per il serverless, il backend remoto deve essere protetto in modo da consentire il traffico solo da API Gateway. API Gateway collegherà un token ID istanza all'intestazione Authorization durante il proxy delle richieste. Il token ID istanza rappresenta il account di servizio di runtime utilizzato per eseguire il deployment di API Gateway. Il backend remoto può quindi verificare che la richiesta provenga da API Gateway in base a questo token allegato.

Ad esempio, un backend remoto di cui è stato eseguito il deployment su Cloud Run può utilizzare Identity and Access Management (IAM) per:

  1. Limita le chiamate non autenticate revocando roles/run.invoker dall'entità speciale allUsers.
  2. Consenti solo ad API Gateway di richiamare il backend concedendo il ruolo roles/run.invoker al account di servizio di runtime di API Gateway.

Per impostazione predefinita, API Gateway creerà il token ID dell'istanza con un pubblico JWT che corrisponde al campo address. 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 address. Per i backend remoti di cui è stato eseguito il deployment su App Engine o con Identity-Aware Proxy (IAP), devi eseguire l'override dell'audience JWT. App Engine e IAP utilizzano il proprio ID client OAuth come pubblico previsto.

Quando questa funzionalità è abilitata, API Gateway modifica le intestazioni nelle richieste. Se una richiesta ha già l'intestazione Authorization impostata, API Gateway:

  1. Copia il valore originale in una nuova intestazione X-Forwarded-Authorization.
  2. Esegui l'override dell'intestazione Authorization con il token ID istanza.

Pertanto, se un client API imposta l'intestazione Authorization, un backend in esecuzione dietro API Gateway deve utilizzare l'intestazione X-Forwarded-Authorization per recuperare l'intero JWT. Il backend deve verificare il JWT in questa intestazione, poiché API Gateway non eseguirà la verifica se i metodi di autenticazione non sono configurati.

Per esempi di configurazione, consulta Crea una configurazione API.

disable_auth

disable_auth: bool

Facoltativo. Questa proprietà determina se API Gateway deve impedire l'ottenimento di un token ID istanza e impedirne il collegamento alla richiesta.

Quando configuri il backend di destinazione, potresti non voler utilizzare IAP o IAM per autenticare le richieste da API Gateway se si applica una di queste condizioni:

  1. Il backend deve consentire le chiamate non autenticate.
  2. Il backend richiede l'intestazione Authorization originale dal client API e non può utilizzare X-Forwarded-Authorization (descritta nella sezione jwt_audience).

In questo caso, imposta questo campo su true.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Facoltativo. Imposta la strategia di traduzione del percorso utilizzata da API Gateway quando invia richieste proxy al backend di destinazione.

Per maggiori dettagli sulla traduzione dei percorsi, consulta la sezione Informazioni sulla traduzione dei percorsi.

Quando x-google-backend viene utilizzato al livello superiore della specifica OpenAPI, path_translation viene impostato su APPEND_PATH_TO_ADDRESS per impostazione predefinita, mentre quando x-google-backend viene utilizzato al livello di operazione della specifica OpenAPI, path_translation viene impostato su CONSTANT_ADDRESS per impostazione predefinita. Se il campo address non è presente, path_translation rimarrà non specificato e non si verificherà.

deadline

deadline: double

Facoltativo. Il numero di secondi di attesa per una risposta completa da una richiesta. Le risposte che richiedono più tempo della scadenza configurata scadranno. Su un endpoint SSE o con trasferimento in blocchi, la scadenza limita comunque la durata dell'intero stream; su un endpoint gRPC o WebSocket, limita invece l'intervallo tra i messaggi. Consulta Imposta la scadenza dello stream per i timeout che si applicano a ogni tipo di richiesta. La scadenza predefinita è 15.0 secondi.

Ometti il campo o impostalo su 0 per utilizzare il valore predefinito. Anche un valore negativo utilizza il valore predefinito, ma è deprecato: la creazione di una configurazione API con un valore negativo restituisce un avviso nei metadati dell'operazione e verrà rifiutata in una release futura.

La scadenza è configurabile fino a 3600 secondi. Un gateway non in streaming applica un massimo inferiore di 600 secondi, rifiutando una scadenza più elevata al momento della creazione o dell'aggiornamento del gateway anziché della creazione della configurazione API.

protocol

protocol: [ http/1.1 | h2 ]

Facoltativo. Il protocollo utilizzato per inviare una richiesta al backend. I valori supportati sono http/1.1 e h2.

Il valore predefinito è http/1.1 per i backend HTTP e HTTPS.

Per i backend HTTP sicuri (https://) che supportano HTTP/2, imposta questo campo su h2 per migliorare le prestazioni. Questa è l'opzione consigliata per i backend serverless Google Cloud .

I requisiti del protocollo dipendono dal tipo di streaming:

  • gRPC: devi impostare il protocollo su h2.
  • WebSockets: devi utilizzare http/1.1.
  • Server-Sent Events (SSE) e invio incrementale delle risposte: puoi utilizzare http/1.1 o h2. Per un rendimento migliore, ti consigliamo di utilizzare h2.

Informazioni sulla traduzione dei percorsi

Quando API Gateway gestisce le richieste, prende il percorso della richiesta originale e lo traduce prima di effettuare una richiesta al backend di destinazione. Il modo esatto in cui avviene questa traduzione dipende dalla strategia di traduzione dei percorsi che utilizzi. Esistono due strategie di traduzione dei percorsi:

  • APPEND_PATH_TO_ADDRESS: il percorso della richiesta del backend di destinazione viene calcolato aggiungendo il percorso della richiesta originale all'URL address dell'estensione x-google-backend.
  • CONSTANT_ADDRESS: il percorso della richiesta di destinazione è costante, come definito dall'URL address dell'estensione x-google-backend. Se il percorso OpenAPI corrispondente contiene parametri, il nome del parametro e il relativo valore diventano parametri di ricerca.

Esempi:

  • APPEND_PATH_TO_ADDRESS
    • address: https://my-project-id.appspot.com/BASE_PATH
    • Con i parametri di percorso OpenAPI
      • Percorso OpenAPI: /hello/{name}
      • Percorso della richiesta: /hello/world
      • URL della richiesta di destinazione: https://my-project-id.appspot.com/BASE_PATH/hello/world
    • Senza parametri di percorso OpenAPI
      • Percorso OpenAPI: /hello
      • Percorso della richiesta: /hello
      • URL della richiesta di destinazione: https://my-project-id.appspot.com/BASE_PATH/hello
  • CONSTANT_ADDRESS
    • address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
    • Con i parametri di percorso OpenAPI
      • Percorso OpenAPI: /hello/{name}
      • Percorso della richiesta: /hello/world
      • URL della richiesta di destinazione: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
    • Senza parametri di percorso OpenAPI
      • Percorso OpenAPI: /hello
      • Percorso della richiesta: /hello
      • URL della richiesta di destinazione: https://us-central1-my-project-id.cloudfunctions.net/helloGET

x-google-endpoints

Questa sezione descrive gli utilizzi dell'estensione x-google-endpoints.

Configura API Gateway per consentire le richieste CORS

Se l'API viene chiamata da un'applicazione web con un'origine diversa, l'API deve supportare la condivisione di risorse multiorigine (CORS). Per informazioni sulla configurazione di API Gateway per il supporto di CORS, consulta Aggiunta del supporto di CORS ad API Gateway.

Se devi implementare il supporto CORS personalizzato nel codice di backend, imposta allowCors: True in modo che API Gateway trasmetta tutte le richieste CORS al codice di backend:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

Aggiungi l'estensione x-google-endpoints al livello più alto del documento OpenAPI (non rientrato o nidificato), ad esempio:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

x-google-issuer

x-google-issuer: URI | EMAIL_ADDRESS

Questa estensione viene utilizzata nella sezione securityDefinitions di OpenAPI per specificare l'emittente di una credenziale. I valori possono assumere la forma di un nome host o di un indirizzo email.

x-google-jwks_uri

x-google-jwks_uri: URI

URI del set di chiavi pubbliche del provider per convalidare la firma del token JWT (JSON Web Token).

Il campo x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) è obbligatorio. API Gateway supporta due formati di chiave pubblica asimmetrica definiti da questa estensione OpenAPI:

  • Formato del set JWK. Ad esempio:

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Ad esempio:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Se utilizzi un formato di chiave simmetrica, imposta x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) sull'URI di un file contenente la stringa della chiave con codifica base64url.

x-google-jwt-locations

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.

In alternativa, utilizza l'estensione x-google-jwt-locations nella sezione securityDefinitions di OpenAPI per fornire le posizioni personalizzate da cui estrarre il token JWT.

L'estensione x-google-jwt-locations accetta un elenco di località JWT. Ogni posizione JWT contiene i seguenti campi:

Element Descrizione
header/query Obbligatorio. Il nome dell'intestazione contenente il JWT o il nome del parametro di query contenente il JWT.
value_prefix Facoltativo. Solo per l'intestazione. Quando value_prefix è impostato, il suo valore deve corrispondere al prefisso del valore dell'intestazione contenente il JWT.

Ad esempio:

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

Se vuoi supportare solo un sottoinsieme delle posizioni JWT predefinite, elencale esplicitamente nell'estensione x-google-jwt-locations. Ad esempio, per includere il supporto solo per l'intestazione Authorization con il prefisso "Bearer ":

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

x-google-audiences

x-google-audiences: STRING

Questa estensione viene utilizzata nella sezione securityDefinitions di OpenAPI per fornire un elenco di segmenti di pubblico che il campo JWT aud deve corrispondere durante l'autenticazione JWT. Questa estensione accetta una singola stringa con valori separati da una virgola. Gli spazi non sono consentiti tra i segmenti di pubblico. Se non viene specificato, il campo JWT aud deve corrispondere al campo host nel documento OpenAPI.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

x-google-management

L'estensione x-google-management controlla diversi aspetti della gestione delle API e contiene i campi descritti in questa sezione.

metrics

Utilizza metrics insieme a quota e x-google-quota per configurare una quota per la tua API. Una quota ti consente di controllare la frequenza con cui le applicazioni possono chiamare i metodi nell'API. Ad esempio:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

Il campo metrics contiene un elenco con le seguenti coppie chiave-valore:

Element Descrizione
nome Obbligatorio. Il nome di questa metrica. In genere, si tratta del tipo di richiesta (ad esempio "read-requests" o "write-requests") che identifica in modo univoco la metrica.
displayName

Facoltativo, ma consigliato. Il testo visualizzato per identificare la metrica nella scheda Quote della pagina Endpoint > Servizi nella consoleGoogle Cloud . Questo testo viene visualizzato anche ai consumer della tua API nelle pagine Quote in IAM e amministrazione e API e servizi. Il nome visualizzato deve contenere un massimo di 40 caratteri.

Per motivi di leggibilità, l'unità del limite di quota associato viene aggiunta automaticamente al nome visualizzato nella consoleGoogle Cloud . Ad esempio, se specifichi "Richieste di lettura" come nome visualizzato, nella consoleGoogle Cloud viene visualizzato "Richieste di lettura al minuto per progetto". Se non specificato, ai consumer della tua API viene visualizzato "unlabeled quota" (quota senza etichetta) nelle pagine Quote in IAM e amministrazione e API e servizi.

Per mantenere la coerenza con i nomi visualizzati dei servizi Google elencati nella pagina Quote che i consumer della tua API vedono, ti consigliamo di utilizzare il seguente nome visualizzato:

  • Utilizza "Richieste" quando hai una sola metrica.
  • Se hai più metriche, ognuna deve descrivere il tipo di richiesta e contenere la parola "richieste" (ad esempio "Richieste di lettura" o "Richieste di scrittura").
  • Utilizza "unità di quota" anziché "richieste" quando uno dei costi associati alla metrica è maggiore di 1.
valueType Obbligatorio. Deve essere INT64
metricKind Obbligatorio. Deve essere DELTA

quota

Specifica il limite della quota per una metrica definita nella sezione quota. Ad esempio:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

Il campo quota.limits contiene un elenco con le seguenti coppie chiave:valore:

Element Descrizione
nome Obbligatorio. Il nome del limite, che deve essere univoco all'interno del servizio. Il nome può contenere lettere minuscole e maiuscole, numeri e "-" (il carattere trattino) e deve avere una lunghezza massima di 64 caratteri.
metrica Obbligatorio. Il nome della metrica a cui si applica questo limite. Questo nome deve corrispondere al testo specificato nel nome di una metrica. Se il testo specificato non corrisponde a un nome di metrica, viene visualizzato un errore quando esegui il deployment del documento OpenAPI.
unità Obbligatorio. L'unità di misura del limite. È supportato solo "1/min/{project}", il che significa che il limite viene applicato per progetto e l'utilizzo viene reimpostato ogni minuto.
valori Obbligatorio. Il limite per la metrica. Devi specificarlo come coppia chiave:valore nel seguente formato: 
STANDARD: YOUR-LIMIT-FOR-THE-METRIC
Sostituisci YOUR-LIMIT-FOR-THE-METRIC con un valore intero che corrisponde al numero massimo di richieste consentite per l'unità specificata (solo al minuto, per progetto). Ad esempio:
values:
  STANDARD: 5000

x-google-quota

L'estensione x-google-quota viene utilizzata nella sezione OpenAPI paths per associare un metodo nell'API a una metrica. Ai metodi per i quali non è definito x-google-quota non vengono applicati limiti di quota. Ad esempio:

x-google-quota:
  metricCosts:
    read-requests: 1

L'estensione x-google-quota contiene il seguente elemento:

Element Descrizione
metricCosts Una coppia chiave-valore definita dall'utente: "YOUR-METRIC-NAME": METRIC-COST.
  • "YOUR-METRIC-NAME": Il testo di "YOUR-METRIC-NAME" deve corrispondere a un nome di metrica definito.
  • METRIC-COST: Un valore intero che definisce il costo per ogni richiesta. Quando viene effettuata una richiesta, la metrica associata viene incrementata del costo specificato. Il costo consente ai metodi di consumare a velocità diverse dalla stessa metrica. Ad esempio, se una metrica ha un limite di quota di 1000 e un costo di 1, l'applicazione chiamante può effettuare 1000 richieste al minuto prima di superare il limite. Con un costo di 2 per la stessa metrica, un'applicazione chiamante può effettuare solo 500 richieste al minuto prima di superare il limite.

Esempi di quote

L'esempio seguente mostra l'aggiunta di una metrica e di un limite per le richieste di lettura e di scrittura.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

x-google-api-name

Quando il servizio contiene una sola API, il nome dell'API corrisponde al nome del servizio API Gateway. (API Gateway utilizza il nome specificato nel campo host del documento OpenAPI come nome del servizio). Quando il servizio contiene più di un'API, specifica i nomi delle API aggiungendo l'estensione x-google-api-name al documento OpenAPI. L'estensione x-google-api-name consente di assegnare un nome esplicito alle singole API e di stabilire un controllo delle versioni indipendente per ciascuna API.

Ad esempio, puoi configurare un servizio denominato api.example.com con due API, producer e consumer, con i frammenti di documento OpenAPI mostrati qui:

  • API Producer in producer.yaml: 

    swagger: 2.0
host: api.example.com
x-google-api-name: producer
info:
  version: 1.0.3

  • API Consumer in consumer.yaml: 

    swagger: 2.0
host: api.example.com
x-google-api-name: consumer
info:
  version: 1.1.0

Puoi eseguire il deployment dei due documenti OpenAPI insieme a:

gcloud api-gateway api-configs create API_CONFIG_ID \
  --api=my-api \
  --openapi-spec="producer.yaml,consumer.yaml" \
  --project=my-project-id