Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

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. Questa pagina descrive le estensioni personalizzate specifiche di Google alla 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

Le estensioni Google OpenAPI hanno nomi che iniziano con il prefisso x-google-.

`x-google-allow`

x-google-allow: [configured | all]

Questa estensione viene utilizzata al livello superiore di una specifica OpenAPI per indicare quali percorsi 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 che hai elencato nella specifica OpenAPI vengono pubblicati 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 e minuscole. Ad esempio, API Gateway considera /widgets e /Widgets come metodi API diversi.

Quando viene utilizzato all, devi prestare particolare attenzione a due aspetti:

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 e minuscole, la tua 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 stai utilizzando. Ti consigliamo di rivedere le impostazioni nel framework per assicurarti che il routing sensibile alle maiuscole sia attivato. Questo consiglio è in linea con la specifica OpenAPI v2.0 che afferma: "Tutti i nomi dei campi nella specifica sono sensibili alle maiuscole".

Esempio

Supponi che:

x-google-allow è impostato su all.
Il metodo API widgets è elencato nella specifica OpenAPI, ma non in 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 la tua API utilizza il routing sensibile alle maiuscole e minuscole (e non hai indirizzato le chiamate a "Widget" a nessun codice), il backend API restituisce un 404. Se, tuttavia, utilizzi il routing senza distinzione tra maiuscole e minuscole, il backend API indirizza questa chiamata a "widgets".

Linguaggi e framework diversi hanno metodi diversi per controllare la distinzione tra maiuscole e minuscole e il routing. Per maggiori dettagli, consulta la documentazione del 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 autenticazione e timeout. Tutte queste configurazioni possono essere applicate in base all'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 quando viene effettuata la richiesta di backend di destinazione.

Quando configuri API Gateway per Serverless, il backend remoto deve essere protetto per consentire solo il traffico 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 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:

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