Questa pagina è stata tradotta dall'API Cloud Translation.

Modificare un gateway per utilizzare OpenAPI 3.x

Questa pagina descrive come modificare un gateway API esistente per utilizzare una specifica OpenAPI 3.x per la configurazione API.

Prima di iniziare

Verifica di avere un'istanza API Gateway esistente configurata con una specifica OpenAPI 2.0.
Installa la CLI gcloud. Per saperne di più, consulta Installa Google Cloud CLI.

Modificare una configurazione API per utilizzare OpenAPI 3.x

Per modificare una configurazione API Gateway OpenAPI 2.0 esistente in modo da utilizzare OpenAPI 3.x, completa i seguenti passaggi:

Trovare la configurazione API attuale

Trova la configurazione API associata al gateway.

Descrivi l'istanza API Gateway:

gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION

Sostituisci quanto segue:

GATEWAY_ID: l'ID del gateway.
PROJECT_ID: l'ID progetto Google Cloud .
GATEWAY_LOCATION: la posizione del gateway.

L'output mostra il percorso apiConfig, ad esempio:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
createTime: '2025-03-25T02:49:58.641650649Z'
defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
displayName: My gateway
name: projects/my-project/locations/us-west1/gateways/my-new-gateway
state: ACTIVE
updateTime: '2025-03-25T02:51:52.674308428Z'

Recuperare il documento OpenAPI

Per ottenere il documento OpenAPI per la configurazione API che hai identificato:

Descrivi la configurazione dell'API:

gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL

Sostituisci quanto segue:

CONFIG_ID: l'ID della configurazione API.
API_ID: l'ID della tua API.
PROJECT_ID: l'ID progetto Google Cloud .

L'output mostra la sezione openapiDocuments, che contiene i contenuti codificati in base64 del documento OpenAPI:

createTime: '2024-02-16T21:11:36.293169474Z'
displayName: my-api-config
gatewayServiceAccount: projects/-/serviceAccounts/api-gateway-sa@my-sandbox.iam.gserviceaccount.com
name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
openapiDocuments:
-   document:
    contents: IyBvc...
    path: apigateway-config.yaml
serviceConfigId: my-api-config-0a1fjkfeb7t8z
state: ACTIVE
updateTime: '2024-02-16T21:13:45.626771120Z'

Decodifica del documento OpenAPI

Per decodificare i contenuti del documento OpenAPI codificato in base64:

Decodifica il valore contents:

echo 'IyBvc...' | base64 -d

Sostituisci IyBvc... con il valore contents effettivo del passaggio precedente.

L'output mostra il documento OpenAPI 2.0, ad esempio:

swagger: '2.0'
info:
  title: API_ID
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0

Converti il documento OpenAPI in OpenAPI 3.x

Puoi utilizzare uno strumento per convertire il documento OpenAPI 2.0 in OpenAPI 3.x. Ad esempio, Swagger Editor fornisce un'utilità di conversione.

Dopo la conversione iniziale a OpenAPI 3.x, applica manualmente eventuali modifiche aggiuntive al documento per allinearlo a OpenAPI 3.x e garantire la compatibilità con le estensioni e le funzionalità di API Gateway. Per ulteriori dettagli sull'estensione OpenAPI 3.x supportata in API Gateway, consulta Estensioni OpenAPI 3.x in API Gateway.

La tabella seguente descrive le modifiche richieste:

Funzionalità	OpenAPI 2.0	OpenAPI 3.x	Descrizione della modifica
Chiave API	`securityDefinitions`	`securitySchemes`	Le chiavi API utilizzano il supporto predefinito delle chiavi API OpenAPI. Gli strumenti di conversione in genere gestiscono questa operazione automaticamente. Non sono necessarie modifiche manuali.
Autenticazione JWT	`x-google-audiences` e così via.	`x-google-auth`	Nelle estensioni OpenAPI 2.0, definisci la configurazione OAuth con estensioni individuali su un'istanza `securityDefinition`. Gli strumenti di conversione convertono l'istanza dello schema di sicurezza in `#/components/securitySchemes` e lasciano le estensioni. Modifica manualmente queste estensioni in modo che siano elementi secondari di `x-google-auth` e rimuovi il prefisso `x-google-`. I valori rimangono invariati.
Quota	`x-google-management`, `x-google-quota`	`x-google-api-management`, `x-google-quota`	Nelle estensioni OpenAPI 2.0, definisci metriche e quota in `x-google-management` e le colleghi con `x-google-quota`. Gli strumenti di conversione lasciano queste estensioni in posizione. Sposta manualmente le metriche e la configurazione delle quote da `x-google-management` a `x-google-api-management`. Modifica la configurazione in modo da utilizzare le chiavi YAML e rimuovi `valueType`, `metricKind` e `unit`. Rimuovere `metricCosts` dalle istanze di `x-google-quota`.
Backend	`x-google-backend`	`x-google-api-management`, `x-google-backend`	Nelle estensioni OpenAPI 2.0, definisci i backend in `x-google-backend` e la configurazione viene applicata dove definito. Nelle estensioni OpenAPI 3.x, definisci il backend in `x-google-api-management` e poi lo applichi con `x-google-backend`. Gli strumenti di conversione lasciano questa estensione in posizione. Sposta manualmente la configurazione su `x-google-api-management`. Modifica le istanze di `x-google-backend` per fare riferimento a questa configurazione.
Endpoint	`x-google-endpoints`	`x-google-endpoint`, `servers`	Nelle estensioni OpenAPI 2.0, definisci la configurazione degli endpoint in `x-google-endpoints`. Nelle estensioni OpenAPI 3.x, utilizzi `x-google-endpoint`, ma è un'estensione di `servers` anziché alla radice. Gli strumenti di conversione lasciano questa estensione in posizione. Sposta manualmente questo valore su `servers` e rimuovi il campo `name`. Ad esempio: # OpenAPI 2.0 x-google-endpoints: - name: "my-api.apigateway.my-project.cloud.goog" allowCors: True # OpenAPI 3.0.x servers: - url: https://my-api.apigateway.my-project.cloud.goog/ x-google-endpoint: allowCors: True
Nomi delle API	`x-google-api-name`	`x-google-api-management`	Nelle estensioni OpenAPI 2.0, definisci i nomi delle API in `x-google-api-name`. Nelle estensioni OpenAPI 3.x, utilizzi un campo `apiName` in `x-google-api-management`. Sposta manualmente questa configurazione su `x-google-api-management`.
Consenti tutto il traffico	`x-google-allow`	NON SUPPORTATO	Rimuovi questo elemento dal documento OpenAPI. API Gateway non supporta questa funzionalità in OpenAPI 3.x.

Crea una nuova configurazione API

Crea una nuova configurazione API utilizzando il documento OpenAPI 3.x modificato.

Crea la configurazione API:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION
```
Sostituisci quanto segue:
- NEW_CONFIG_ID: un nuovo ID per la configurazione API.
- API_ID: l'ID della tua API.
- PROJECT_ID: l'ID progetto Google Cloud .
- NEW_API_DEFINITION: il percorso del file di specifica OpenAPI 3.x.

Aggiorna il gateway

Aggiorna l'istanza del gateway in modo che faccia riferimento alla nuova configurazione API dal documento OpenAPI 3.x modificato.

Aggiorna il gateway:
```
gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
```
Sostituisci quanto segue:
- GATEWAY_ID: l'ID del gateway.
- API_CONFIG: il percorso completo della risorsa della nuova configurazione API, ad esempio: projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
- PROJECT_ID: l'ID progetto Google Cloud .
- GATEWAY_LOCATION: la posizione del gateway.

Passaggi successivi

Scopri di più su API Gateway.
Esplora la specifica OpenAPI.