Dopo aver configurato Cloud Endpoints in un documento OpenAPI, esegui il deployment in modo che gli endpoint dispongano delle informazioni necessarie per gestire l'API.
Per eseguire il deployment della configurazione di Endpoints, utilizza il comando gcloud
endpoints services deploy
. Questo comando utilizza Service Infrastructure, la piattaforma di servizi di base di Google, utilizzata da Endpoints e altri servizi per creare e gestire API e servizi. Questa pagina descrive come eseguire il deployment di un documento OpenAPI su Endpoints.
Prerequisiti
Per iniziare, questa pagina presuppone che tu abbia:
È stato creato un progetto Google Cloud in cui disponi del ruolo Editor o Proprietario. Dopo il deployment iniziale, puoi concedere il ruolo Editor configurazione servizio più restrittivo a un account utente, gruppo o di servizio. Per ulteriori informazioni, consulta Concessione e revoca dell'accesso all'API.
Se utilizzi un nome di dominio personalizzato (come
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
Per eseguire il deployment della configurazione, puoi utilizzare lo strumento a riga di comando gcloud
. Consulta la pagina di
riferimento gcloud per ulteriori informazioni sui comandi.
Per prepararti al deployment:
- Installa e inizializza gcloud CLI.
- Aggiorna gcloud CLI:
gcloud components update
- Assicurati che gcloud CLI sia autorizzato ad accedere ai tuoi dati e 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 l'ID progetto Google Cloudgcloud config set project [YOUR-PROJECT-ID]
- Se esegui il deployment del backend dell'API su Kubernetes o Kubernetes Engine, esegui questo comando per acquisire nuove credenziali utente da utilizzare per le Credenziali predefinite dell'applicazione. Le credenziali utente sono necessarie per autorizzare
kubectl
.gcloud auth application-default login
Si apre una nuova scheda del browser e ti viene chiesto di scegliere un account.
Convalida della sintassi di 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 di convalida JSON come vim
, usare un servizio di linter JSON online o usare Python, ad esempio:
python -m json.tool openapi.json
Per migliorare la leggibilità, puoi stampare in modo discreto il file JSON:
python -m json.tool input.json > output.json
Sostituisci input.json
con il percorso del file openapi.json
. output.json
è
il file JSON in stampatello.
Convalida del documento OpenAPI in corso...
Non tutti i costrutti OpenAPI sono attualmente supportati da Cloud Endpoints. Prima di eseguire il deployment, puoi convalidare il tuo documento OpenAPI.
Per convalidare il tuo documento OpenAPI:
Cambia la directory nella posizione contenente 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 seguente comando 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 questo comando e sostituisci
[YOUR_OPENAPI_DOCUMENT]
con il nome del documento OpenAPI che descrive la tua 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
del documento OpenAPI. Quando specifichi il flag --validate-only
, viene comunque creato un servizio, ma non viene eseguito il deployment della configurazione. Non c'è un modo per convalidare il tuo documento OpenAPI senza creare un servizio. Anche se puoi eliminare il servizio, Service Management 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 eseguire il deployment dell'API, esegui Google Cloud CLI, che utilizza Service Management per caricare la configurazione dell'API e per creare (o aggiornare) un servizio gestito.
Per eseguire il deployment del tuo documento OpenAPI:
Cambia la directory nella posizione contenente il documento OpenAPI.
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 del progetto Google Cloud in cui vuoi creare il servizio:gcloud config set project [YOUR_PROJECT_ID]
Esegui questo comando e sostituisci
[YOUR_OPENAPI_DOCUMENT]
con il nome del documento OpenAPI che descrive la tua 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 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 invia le informazioni al terminale. Una volta completato, viene visualizzata una riga come la seguente, che mostra 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 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 viene visualizzato un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione degli endpoint.
Nuova distribuzione in corso...
Ogni volta che modifichi qualcosa nel documento OpenAPI, assicurati di eseguirne di nuovo il deployment in modo che Endpoints disponga della versione più recente della configurazione del servizio dell'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 in modo che utilizzi l'ultima configurazione del servizio di cui è stato eseguito il deployment. Quando specifichi questa opzione, fino a 5 minuti dopo il deployment di una nuova configurazione del servizio, ESP rileva la modifica e inizia automaticamente a utilizzarla. Ti consigliamo di specificare questa opzione anziché un ID di configurazione specifico da utilizzare per ESP.
Dopo il deployment iniziale della configurazione di Endpoints, 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 Concessione e revoca dell'accesso all'API.
Passaggi successivi
- Guida introduttiva all'utilizzo del portale Cloud Endpoints
- Deployment del backend dell'API
- Deployment su Kubernetes
- Esecuzione di ESP in locale o su un'altra piattaforma
- Recupero del nome del servizio e dell'ID di configurazione