Eseguire il deployment della configurazione di Endpoints

API Open | gRPC

Dopo aver configurato Cloud Endpoints in un documento OpenAPI, ne esegui il deployment in modo che gli endpoint dispongano delle informazioni necessarie per gestire la tua API. Per eseguire il deployment della configurazione Endpoint, utilizza il comando gcloud endpoints services deploy. Questo comando utilizza Service Infrastructure, la piattaforma di servizi di base di Google, utilizzata da Endpoints e da altri servizi per creare e gestire API e servizi. In questa pagina viene descritto come eseguire il deployment di un documento OpenAPI in endpoint.

Prerequisiti

Come punto di partenza, in questa pagina si presuppone che tu disponga di:

È stato creato un progetto Google Cloud in cui hai il ruolo Editor o Proprietario. Dopo il deployment iniziale, puoi concedere il ruolo Editor di configurazione del servizio più restrittivo a un account utente, gruppo o servizio. Per ulteriori informazioni, consulta Concedere e revocare l'accesso all'API.
Configurato Endpoints.
Se utilizzi un nome di dominio personalizzato (ad esempio my-api.example.com), devi verificare il nome di dominio prima di poter eseguire il deployment del documento OpenAPI.

Preparazione di Google Cloud CLI per il deployment

Puoi utilizzare lo strumento a riga di comando gcloud per eseguire il deployment della configurazione. Consulta la guida di riferimento di gcloud per ulteriori informazioni sui comandi.

Per prepararti al deployment:

Installa e inizializza l'interfaccia a riga di comando gcloud.
Aggiorna l'interfaccia a riga di comando gcloud:
```
gcloud components update
```
Assicurati che l'interfaccia a riga di comando gcloud sia autorizzata ad accedere ai dati e ai servizi:
```
gcloud auth login
```
Si apre una nuova scheda del browser e ti viene chiesto di scegliere un account.
Imposta il progetto predefinito. Sostituisci [YOUR-PROJECT-ID] con il tuo ID progetto GCP
```
gcloud config set project [YOUR-PROJECT-ID]
```
Se eseguirai il deployment del backend dell'API in Kubernetes o Kubernetes Engine, esegui questo comando per acquisire le nuove credenziali utente da utilizzare per le credenziali predefinite dell'applicazione. Per autorizzare kubectl sono necessarie le credenziali utente.
```
gcloud auth application-default login
```
Si apre una nuova scheda del browser e ti viene chiesto di scegliere un account.

Convalida della sintassi `openapi.json` in corso...

Il file del documento OpenAPI può essere in formato YAML o JSON. Se è in formato JSON, ti consigliamo di verificare la sintassi prima di eseguire il deployment del file. Per verificare che openapi.json sia un file JSON ben formattato, puoi aprirlo in un editor di testo con convalida JSON come vim, utilizzare un servizio linter JSON online o utilizzare Python, ad esempio:

python -m json.tool openapi.json

Per migliorare la leggibilità, puoi stampare il file JSON in modo molto semplice:

python -m json.tool input.json > output.json

Sostituisci input.json con il percorso del file openapi.json. output.json è il file JSON stampato.

Convalida del documento OpenAPI

Non tutti i costrutti OpenAPI sono attualmente supportati da Cloud Endpoints. Prima di eseguire il deployment, puoi convalidare il documento OpenAPI.

Per convalidare il documento OpenAPI:

Sostituisci la directory con la posizione che contiene il documento OpenAPI.
Conferma il progetto Google Cloud in cui vuoi creare il servizio. Se utilizzi un nome di dominio personalizzato (ad esempio myapi.example.com), assicurati di convalidare l'ID progetto restituito dal comando seguente in modo 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 del progetto Google Cloud in cui vuoi creare il servizio:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Esegui il comando seguente e sostituisci [YOUR_OPENAPI_DOCUMENT] con il nome del documento OpenAPI che descrive l'API:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
```

Il comando gcloud chiama quindi l'API Service Management per creare un servizio gestito con il nome specificato nel campo host nel documento OpenAPI. Quando specifichi il flag --validate-only, viene comunque creato un servizio, ma non viene eseguito il deployment della configurazione. Non esiste un modo per convalidare il documento OpenAPI senza creare un servizio. Anche se puoi eliminare il servizio, la gestione dei servizi ti impedisce di creare un servizio con lo stesso nome per un periodo di circa 30 giorni.

Deployment del documento OpenAPI

Quando è tutto pronto per il deployment dell'API, esegui Google Cloud CLI, che utilizza Service Management per caricare la configurazione dell'API e creare (o aggiornare) un servizio gestito.

Per eseguire il deployment del documento OpenAPI:

Sostituisci la directory con la posizione che contiene il documento OpenAPI.
Convalida l'ID progetto restituito dal comando seguente 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 di Google Cloud in cui vuoi creare il servizio:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Esegui il comando seguente e sostituisci [YOUR_OPENAPI_DOCUMENT] con il nome del documento OpenAPI che descrive l'API:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
```

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

Durante la creazione e la configurazione del servizio, Service Management fornisce informazioni al terminale. Una volta completata l'operazione, verrà visualizzata una riga simile alla seguente che mostra l'ID configurazione del servizio e il nome 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 configurazione del servizio e echo-api.endpoints.example-project-12345.cloud.goog è il nome servizio.

Una volta eseguito il deployment, puoi visualizzare l'API nella pagina Endpoint > Servizi in Google Cloud Console.

Se viene visualizzato un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione degli endpoint.

Nuova implementazione

Ogni volta che modifichi qualcosa nel documento OpenAPI, assicurati di eseguirne nuovamente il deployment in modo che Endpoints abbia la versione più recente della configurazione del servizio dell'API. Non è necessario eseguire di nuovo il deployment o riavviare ESP se hai già eseguito il deployment di ESP con rollout opzione impostata su managed. Questa opzione configura ESP in modo che utilizzi l'ultima configurazione del servizio di cui è stato eseguito il deployment. Quando specifichi questa opzione, fino a cinque 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 di configurazione specifico da utilizzare per ESP.

Dopo il deployment iniziale della configurazione degli endpoint, puoi concedere a un utente, a un account di servizio o a un gruppo un ruolo che consenta di eseguire nuovamente il deployment della configurazione degli endpoint. Per ulteriori informazioni, consulta Concedere e revocare l'accesso all'API.