Cloud Endpoints Frameworks fornisce funzionalità di gestione delle API paragonabili a quelle fornite da Extensible Service Proxy (ESP) per Cloud Endpoints. Endpoints Frameworks include un gateway API integrato che intercetta tutte le richieste ed esegue tutti i controlli necessari, ad esempio l'autenticazione, prima di inoltrare la richiesta al backend API. Quando il backend risponde, Endpoints Frameworks raccoglie e segnala la telemetria. Puoi visualizzare le metriche per la tua API nella pagina Endpoint > Servizi nella console Google Cloud.
Le funzionalità di gestione delle API disponibili in Endpoints Frameworks includono:
Affinché l'API venga gestita da Endpoints, devi eseguire il deployment di un documento OpenAPI che descriva l'API utilizzando la versione 2.0 della specifica OpenAPI. Questa pagina descrive come generare ed eseguire il deployment di un documento OpenAPI che consente a Endpoints di gestire la tua API.
Se non aggiungi la gestione delle API, la tua API continua a gestire le richieste, ma l'API non viene visualizzata nella pagina Endpoint > Servizi della console Google Cloud e la funzionalità fornita dagli endpoint, come il logging, il monitoraggio e l'impostazione delle quote, non è disponibile.
Installazione e configurazione del software richiesto
Se non l'hai ancora fatto, installa e configura Google Cloud CLI per Python e aggiungi la libreria Python di Endpoints Frameworks alla directory del progetto API, in modo che venga caricata con il codice API al momento del deployment
Installa e configura gcloud CLI per Python
Installa e inizializza gcloud CLI:
Installa il componente
gcloud
che include l'estensione App Engine per Python:gcloud components install app-engine-python
Aggiorna gcloud CLI:
gcloud components update
Assicurati che gcloud CLI sia autorizzato ad accedere ai tuoi dati e servizi su Google Cloud:
gcloud auth login
Si apre una nuova scheda del browser e ti viene chiesto di scegliere un account.
Imposta il progetto predefinito sul tuo ID progetto. Sostituisci
YOUR_PROJECT_ID
con l'ID del tuo progetto Google Cloud.gcloud config set project YOUR_PROJECT_ID
Per Linux, imposta la variabile di ambiente
ENDPOINTS_GAE_SDK
sul percorso della cartella dell'SDK di App Engine:PATH_TO_CLOUD_SDK/platform/google_appengine
Sostituisci
PATH_TO_CLOUD_SDK
con l'output del seguente comando:gcloud info --format="value(installation.sdk_root)"
Aggiungi la libreria Python di Endpoints Frameworks
Assicurati di poter compilare estensioni C per Python.
Windows: è richiesto Microsoft Visual C++ 9.0 o versioni successive. Puoi scaricare il compilatore Microsoft Visual C++ per Python 2.7 dal Centro download Microsoft
Altri sistemi operativi: a seconda del sistema operativo, potrebbe essere necessario installare gli strumenti di compilazione (a volte in un pacchetto chiamato
build-essential
) e/o le intestazioni di sviluppo Python (a volte in un pacchetto chiamatopython-dev
).
Cambia la directory nella directory principale della tua API.
Crea una sottodirectory
/lib
nella directory principale dell'API:mkdir lib
Installa la libreria:
pip install -t lib google-endpoints --ignore-installed
Genera il documento OpenAPI
Dalla directory principale dell'API, genera un documento OpenAPI utilizzando gli strumenti del framework. Ad esempio:
Classe singola
Nel comando seguente, sostituisci YOUR_PROJECT_ID
con l'ID del tuo progetto Google Cloud.
python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi \ --hostname YOUR_PROJECT_ID.appspot.com
Ignorare gli avvisi visualizzati.
Più classi
Puoi elencare più classi nella riga di comando. Gli endpoint generano un documento OpenAPI per ogni combinazione di nome/versione dell'API.
Se vuoi eseguire il deployment di più classi API con nomi API diversi nell'ambito di un unico servizio, devi aggiungere anche il flag --x-google-api-name
.
L'attivazione di questo flag aggiunge ulteriori limitazioni ai nomi delle API. In particolare, i nomi devono corrispondere all'espressione regolare [a-z][a-z0-9]{0,39}
, ovvero devono essere composti da 1-40 caratteri, che possono essere tutti caratteri alfabetici minuscoli o numeri, tranne per il fatto che il primo carattere non deve essere un numero. Ad esempio:
Nel comando seguente, sostituisci YOUR_PROJECT_ID
con l'ID del tuo progetto Google Cloud.
python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \ --hostname YOUR_PROJECT_ID.appspot.com \ --x-google-api-name
Ignorare gli avvisi visualizzati.
Gli endpoint utilizzano il testo specificato nell'argomento hostname
come nome del servizio. Quando esegui il deployment dell'API in App Engine, viene creata automaticamente una voce DNS con un nome nel formato YOUR_PROJECT_ID.appspot.com
.
Esegui il deployment del documento OpenAPI
Classe singola
gcloud endpoints services deploy echov1openapi.json
Più classi
Se disponi di più documenti OpenAPI, elencali tutti nella riga di comando. Ad esempio:
gcloud endpoints services deploy foov1openapi.json barv1openapi.json
La prima volta che esegui il deployment del documento (o dei documenti) OpenAPI, viene creato un nuovo servizio endpoint con il nome YOUR_PROJECT_ID.appspot.com
.
Al completamento riuscito, una riga simile alla seguente mostra l'ID configurazione del servizio e il nome del servizio:
Service Configuration 2017-02-13r0 uploaded for service example-project-12345.appspot.com
Nell'esempio precedente, 2017-02-13r0
è l'ID configurazione del servizio. L'ID di configurazione del servizio è costituito da un indicatore della data seguito da un numero di revisione. Se esegui di nuovo il deployment del documento OpenAPI, il numero di revisione viene incrementato nell'ID configurazione del servizio.
Se devi visualizzare di nuovo l'ID di configurazione del servizio, esegui questo comando, ma sostituisci YOUR_PROJECT_ID
con l'ID del tuo progetto Google Cloud:
gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com
Puoi creare il tuo documento OpenAPI ed eseguirne il deployment, anziché utilizzarne uno generato. Sostituisci echov1openapi.json
sopra con il percorso del documento OpenAPI. Per ulteriori informazioni sulla scrittura di un documento OpenAPI, consulta la panoramica di OpenAPI.
Esegui di nuovo il deployment dell'API ed esegui il test
Modifica il file di progetto
app.yaml
e aggiungi una sezioneenv_variables
come segue:env_variables: ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION
Sostituisci
YOUR_PROJECT_ID
con l'ID progetto Google Cloud eYOUR_SERVICE_VERSION
con l'ID configurazione del servizio della sezione precedente. Con questa aggiunta al fileapp.yaml
, gli endpoint gestiscono l'API dopo che hai eseguito nuovamente il deployment dell'applicazione.Esegui di nuovo il deployment dell'applicazione:
gcloud app deploy
Attendi qualche momento per la riuscita del deployment, ignorando i messaggi di avviso. Al termine del deployment, viene visualizzato un messaggio simile al seguente:
File upload done. Updating service [default]...done.
Testa per un redeployment riuscito, ad esempio, utilizzando curl:
curl --request POST \ --header "Content-Type: application/json" \ --data '{"content":"echo"}' \ https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2
Sostituisci
echo
con il nome della tua API.I risultati dovrebbero essere simili a:
{ "content": "echo echo" }
Effettua alcune richieste aggiuntive alla tua API.
Per visualizzare le metriche dell'API, apri la pagina Endpoint > Servizi nella console Google Cloud relativa al tuo progetto: