Modificare Cloud Endpoints per utilizzare OpenAPI 3.x

Questa pagina descrive come utilizzare una specifica OpenAPI 3.x durante la configurazione di Endpoints.

Prima di iniziare

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

Modifica la configurazione di Endpoints per utilizzare OpenAPI 3.x

Completa i seguenti passaggi per modificare una configurazione Endpoints OpenAPI 2.0 esistente in modo da utilizzare OpenAPI 3.x.

Visualizzare la cronologia dei deployment

Per visualizzare la cronologia del deployment:

  1. Nella console Google Cloud , vai alla pagina Endpoint > Servizi.

    Vai alla pagina Servizi endpoint

  2. Dall'elenco dei progetti, seleziona il tuo progetto.

  3. Se hai più di un'API, seleziona un'API dall'elenco.

  4. Per visualizzare un elenco dei deployment della configurazione del servizio, fai clic sulla scheda Cronologia deployment. L'elenco mostra:

    • L'ID configurazione.
    • La data di deployment della configurazione del servizio.
    • Chi ha eseguito il deployment della configurazione del servizio.

Visualizzare la configurazione del servizio

Nella scheda Cronologia deployment, seleziona l'ultimo deployment dall'elenco. Vengono visualizzati i contenuti del file di configurazione del servizio di cui è stato eseguito il deployment.

Converti il documento OpenAPI in OpenAPI 3.x

Converti il documento OpenAPI 2.0 in OpenAPI 3.x. Puoi utilizzare uno strumento che supporti questa conversione 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 Endpoints.

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.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. Endpoints non supporta questa funzionalità in OpenAPI 3.x.

Esegui nuovamente il deployment della configurazione del servizio

Ogni volta che modifichi qualcosa nel documento OpenAPI, assicurati di eseguirne nuovamente il deployment in modo che Endpoints disponga della versione più recente della configurazione del servizio della tua API. Non è necessario eseguire nuovamente il deployment o riavviare ESP se in precedenza hai eseguito il deployment di ESP con l'opzione rollout impostata su managed. Questa opzione configura ESP per utilizzare la configurazione del servizio di cui è stato eseguito il deployment più recente. Quando specifichi questa opzione, fino a 5 minuti dopo il deployment di una nuova configurazione del servizio, ESP rileva la modifica e inizia a utilizzarla automaticamente. Ti consigliamo di specificare questa opzione anziché un ID configurazione specifico da utilizzare per ESP.

Per eseguire il deployment del documento OpenAPI:

  1. Passa alla directory contenente il documento OpenAPI.

  2. Convalida l'ID progetto restituito dal seguente comando per assicurarti che il servizio non venga creato nel progetto sbagliato.

    gcloud config list project

    Se devi modificare il progetto predefinito, esegui il comando seguente e sostituisci YOUR_PROJECT_ID con l'ID progetto Google Cloud in cui vuoi creare il servizio:

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. Esegui il seguente comando e sostituisci YOUR_OPENAPI_DOCUMENT con il nome del documento OpenAPI che descrive la tua API:

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

La prima volta che esegui il comando precedente, Service Management crea un nuovo servizio Endpoints nel progetto predefinito con un nome corrispondente al testo specificato nel campo host del documento OpenAPI e carica la configurazione del servizio.

Durante la creazione e la configurazione del servizio, Service Management visualizza informazioni nel terminale. Al termine, viene visualizzata una riga simile alla seguente, in cui sono visualizzati l'ID configurazione del servizio e il nome del servizio:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Nell'esempio precedente, 2017-02-13r0 è l'ID di configurazione del servizio e echo-api.endpoints.example-project-12345.cloud.goog è il nome del servizio.

Dopo un deployment riuscito, puoi visualizzare l'API nella pagina Endpoint > Servizi nella console Google Cloud .

Se ricevi un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione di Endpoints.

Passaggi successivi