Questa pagina mostra come configurare, eseguire il deployment e inviare richieste a un'API di esempio utilizzando Cloud Endpoints Frameworks per Python. Endpoints Frameworks per Python è integrato con l'ambiente di runtime Python 2.7 standard di App Engine. Endpoints Frameworks è costituito da strumenti, librerie e funzionalità che consentono di generare API e librerie client da un'applicazione App Engine.
Obiettivi
Utilizza il seguente elenco di attività di alto livello mentre svolgi il tutorial. Tutte le attività sono necessarie per inviare correttamente richieste all'API.
- Configurare un progetto Google Cloud. Consulta Prima di iniziare.
- Installa il software richiesto e crea un'applicazione App Engine. Vedi Installazione e configurazione del software richiesto.
- Scarica il codice campione. Consulta Ottenere il codice di esempio.
- Generare un documento OpenAPI. Consulta la pagina Configurazione di Endpoints.
- Eseguire il deployment della configurazione di Endpoints per creare un servizio Endpoints. Vedi Eseguire il deployment della configurazione di Endpoints.
- Esegui l'esempio sul computer. Consulta Esecuzione dell'esempio in locale.
- Crea un backend per gestire l'API ed eseguirne il deployment. Vedi Deployment del backend dell'API.
- Invia una richiesta all'API. Vedi Invio di una richiesta all'API.
- Monitora l'attività dell'API. Consulta la pagina Monitoraggio dell'attività dell'API.
- Evita addebiti sul tuo account Google Cloud. Consulta Eseguire la pulizia.
Costi
In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:
Per generare una stima dei costi basata sull'utilizzo previsto,
utilizza il Calcolatore prezzi.
Una volta completate le attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la pagina Pulizia.
Prima di iniziare
- Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
- Prendi nota dell'ID progetto Google Cloud perché sarà necessario in seguito.
Installazione e configurazione del software richiesto
- Segui le istruzioni in Installazione di Google Cloud CLI per Python per configurare il tuo ambiente di sviluppo standard di App Engine. Assicurati di installare i componenti
gcloud
app-engine-python
eapp-engine-python-extras
. - Esegui questi comandi:
-
Aggiorna gcloud CLI.
gcloud components update
-
Assicurati che Google Cloud CLI (
gcloud
) sia autorizzato ad accedere ai tuoi dati e servizi su Google Cloud:gcloud auth login
- Nella nuova scheda del browser che si apre, scegli un account.
-
Imposta il progetto predefinito sul tuo ID progetto.
gcloud config set project [YOUR_PROJECT_ID]
Sostituisci
[YOUR_PROJECT_ID]
con l'ID del tuo progetto Google Cloud. Se hai altri progetti Google Cloud e vuoi utilizzaregcloud
per gestirli, consulta Gestione delle configurazioni di gcloud CLI.
-
Aggiorna gcloud CLI.
-
Devi avere un'applicazione per inviare richieste all'API di esempio.
- Utenti Linux e macOS: questo tutorial fornisce un esempio dell'utilizzo di
curl
, che in genere è preinstallato sul sistema operativo. Se non hai l'appcurl
, puoi scaricarla dalla paginacurl
Release e download. - Utenti Windows: questo tutorial fornisce un esempio utilizzando
Invoke-WebRequest
, che è supportato in PowerShell 3.0 e versioni successive.
- Utenti Linux e macOS: questo tutorial fornisce un esempio dell'utilizzo di
- Assicurati che il tuo ambiente di sviluppo Python includa pip.
- Assicurati di poter compilare le 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 strumenti di compilazione (a volte in un pacchetto chiamato
build-essential
) o le intestazioni di sviluppo Python (a volte in un pacchetto chiamatopython-dev
).
-
Per Linux, imposta la variabile di ambiente
ENDPOINTS_GAE_SDK
sul percorso della cartella dell'SDK App Engine:[Path-to-Google-Cloud-SDK]/platform/google_appengine
.Sostituisci
[Path-to-Google-Cloud-SDK]
con l'output del comando seguente:gcloud info --format="value(installation.sdk_root)"
- Crea un'applicazione App Engine:
- Seleziona la regione in cui vuoi creare l'applicazione App Engine. Esegui questo comando per ottenere un elenco delle regioni:
gcloud app regions list
- Crea un'applicazione App Engine utilizzando il comando seguente.
Sostituisci
[YOUR_PROJECT_ID]
con l'ID progetto Google Cloud e[YOUR_REGION]
con la regione in cui vuoi creare l'applicazione App Engine.gcloud app create \ --project=[YOUR_PROJECT_ID] \ --region=[YOUR_REGION]
Ad esempio:
gcloud app create --project=example-project-12345 --region=us-central
- Seleziona la regione in cui vuoi creare l'applicazione App Engine. Esegui questo comando per ottenere un elenco delle regioni:
recupera il codice di esempio
Per clonare l'API di esempio da GitHub:
Clona il repository di esempio sulla tua macchina locale:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
Passa alla directory contenente il codice campione:
cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Configurazione di Endpoints
Per configurare Endpoints, devi prima installare la libreria Python dei framework endpoint. Potrai quindi utilizzare uno strumento della libreria di framework endpoint per generare un documento OpenAPI per l'API di esempio. Affinché Endpoints possa gestire l'API, devi disporre della libreria di Endpoints Frameworks e del documento OpenAPI. Per scoprire di più, consulta la pagina relativa all'aggiunta della gestione delle API.
Installazione della libreria di Endpoints Frameworks
Questa sezione illustra come utilizzare pip
di Python per aggiungere la libreria di framework endpoint alla directory del progetto dell'API di esempio.
Per aggiungere la libreria di Endpoints Frameworks all'esempio:
Assicurati di essere nella directory principale dell'API di esempio,
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
.Crea una sottodirectory
/lib
nel progetto:mkdir lib
Dalla directory principale di esempio
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
, esegui il comando di installazione:pip install --target lib --requirement requirements.txt --ignore-installed
Tieni presente quanto segue:
Questo comando
pip
può utilizzare GNU Compiler Collection (GCC) per compilare i moduli di estensione. Se usi macOS ed è la prima volta che esegui GCC sul tuo sistema, potresti dover accettare la licenza XCode di Apple. Per farlo, eseguisudo xcodebuild -license
.Se sul computer sono installate più versioni di Python, assicurati di utilizzare una versione di
pip
corrispondente a quella di Python che stai usando in questo tutorial. Le mancate corrispondenze delle versioni (ad esempiopip
da Python 3.4 quando si utilizzapython
da Python 2.7) possono causare errori difficili da comprendere. Se necessario, puoi eseguire pip come modulo Python: sostituiscipip
nel comando precedente conpython -m pip
.Se
pip
non riesce a trovare un pacchetto adatto durante l'esecuzione del comando, prova a eseguirne l'upgrade eseguendopip install --upgrade pip
. Al termine dell'upgrade, prova a eseguire nuovamente il comando di installazione.In alcune release di Debian e Ubuntu
pip
potrebbe non funzionare con DistutilsOptionError. Se viene visualizzato questo errore, aggiungi il flag --system.
Una volta completata, la directory lib
viene compilata con i file necessari per creare l'applicazione Endpoints Frameworks.
Generazione del documento OpenAPI
Puoi utilizzare uno strumento della libreria di Endpoints Frameworks per generare un documento che descriva l'API REST del codice campione.
Per generare il documento OpenAPI:
Assicurati di essere nella directory principale di esempio:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Genera il documento OpenAPI:
python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
Sostituisci
[YOUR_PROJECT_ID]
con l'ID del tuo progetto Google Cloud. Ignorare gli avvisi visualizzati. Lo strumento Endpoints genera un documento OpenAPI denominatoechov1openapi.json
nella directory attuale. Lo strumento Endpoints assegna un nome al file in base al nome e alla versione del servizio specificati nel decorator@endpoints.api
. Per ulteriori informazioni, consulta Creazione dell'API.Endpoints utilizza il testo specificato nell'argomento
hostname
come nome del servizio. Il formato del nomeYOUR_PROJECT_ID.appspot.com
corrisponde alla voce DNS creata automaticamente quando esegui il deployment dell'API nel backend App Engine. Quindi, in questo caso, il nome del servizio Endpoints e il nome di dominio completo (FQDN) corrispondono.
Una volta completato, viene visualizzato il seguente messaggio:
OpenAPI spec written to ./echov1openapi.json
esegui il deployment della configurazione di Endpoints
Per eseguire il deployment della configurazione di Endpoints, utilizza Service Infrastructure, la piattaforma di servizi di base di Google, utilizzata da Endpoints e altri servizi per creare e gestire le API e i servizi.
Per eseguire il deployment del file di configurazione:
- Assicurati di essere nella directory principale di esempio:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
- Esegui il deployment del documento OpenAPI generato nella sezione precedente eseguendo questo comando:
gcloud endpoints services deploy echov1openapi.json
Viene creato un nuovo servizio Endpoints con il nome specificato nell'argomento
hostname
quando hai eseguito lo strumento Endpoint per generare il documento OpenAPI. Indipendentemente dal nome del servizio Endpoints, quando esegui il deployment dell'API su App Engine, viene creato un record DNS utilizzando il formato del nomeYOUR_PROJECT_ID.appspot.com
, ovvero il nome di dominio completo che utilizzi quando invii richieste all'API.Durante la creazione e la configurazione del servizio, Service Management invia una grande quantità di informazioni al terminale. Puoi ignorare tranquillamente gli avvisi relativi ai percorsi in
echov1openapi.json
che non richiedono una chiave API. Al completamento del deployment, viene visualizzato un messaggio simile al seguente:Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
Nell'esempio precedente,
2017-02-13-r2
è l'ID configurazione del servizio eexample-project-12345.appspot.com
è il nome del servizio.Per saperne di più, consulta
gcloud endpoints services deploy
nella documentazione di riferimento digcloud
.
Controllo dei servizi richiesti
Per fornire la gestione delle API, Endpoints Frameworks richiede i seguenti servizi:Nome | Titolo |
---|---|
servicemanagement.googleapis.com |
API Service Management |
servicecontrol.googleapis.com |
API Service Control |
endpoints.googleapis.com |
Google Cloud Endpoints |
Nella maggior parte dei casi, il comando gcloud endpoints services deploy
abilita questi servizi richiesti. Tuttavia, il comando gcloud
viene completato correttamente, ma non abilita i servizi richiesti nelle seguenti circostanze:
Se hai utilizzato un'applicazione di terze parti come Terraform e non includi questi servizi.
Hai eseguito il deployment della configurazione di Endpoints in un progetto Google Cloud esistente in cui questi servizi sono stati disabilitati esplicitamente.
Utilizza il seguente comando per confermare che i servizi richiesti siano abilitati:
gcloud services list
Se i servizi richiesti non sono elencati, abilitali:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
Abilita anche il servizio Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Per determinare ENDPOINTS_SERVICE_NAME puoi:
Dopo aver eseguito il deployment della configurazione di Endpoints, vai alla pagina Endpoint nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è mostrato sotto la colonna Nome servizio.
Per OpenAPI, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel campo
host
della specifica OpenAPI. Per gRPC, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel camponame
della configurazione degli endpoint gRPC.
Per maggiori informazioni sui comandi gcloud
, consulta la pagina relativa ai
servizi gcloud
.
Esecuzione dell'esempio in locale
Dopo aver eseguito il deployment della configurazione di Endpoints, puoi eseguire l'esempio in locale utilizzando il server di sviluppo locale.
Assicurati di essere nella directory principale di esempio:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Avvia il server di sviluppo locale:
dev_appserver.py ./app.yaml
Per impostazione predefinita, il server di sviluppo rimane in ascolto su
http://localhost:8080
, come indicato nei log della console Google Cloud stampati dadev_appserver.py
:INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
Invia una richiesta al server di sviluppo locale:
Linux o Mac OS
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
http://localhost:8080/_ah/api/echo/v1/echo
Nei curl
precedenti:
- L'opzione
--data
consente di specificare i dati da pubblicare nell'API. - L'opzione
--header
specifica che i dati sono in formato JSON.
PowerShell
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} `
-URI "http://localhost:8080/_ah/api/echo/v1/echo").Content
Nell'esempio precedente, le prime due righe terminano con un accento grave. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo l'accento grave. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.
L'API restituisce un'eco al messaggio che lo invii e risponde con quanto segue:
{
"message": "hello world"
}
esegui il deployment del backend dell'API
Finora hai eseguito il deployment del documento OpenAPI in Service Management, ma non hai ancora eseguito il deployment del codice per il backend dell'API. Questa sezione illustra il deployment dell'API di esempio in App Engine.
Per eseguire il deployment del backend dell'API:
- Visualizza l'ID configurazione del servizio eseguendo questo comando:
gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
Sostituisci
[YOUR_PROJECT_ID]
con l'ID progetto. Ad esempio:gcloud endpoints configs list --service=example-project-12345.appspot.com
- Apri il file
app.yaml
nella directorypython-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
. - Apporta le seguenti modifiche nella sezione
env_variables
:- Nel campo
ENDPOINTS_SERVICE_NAME
, sostituisciYOUR-PROJECT-ID
con il tuo ID progetto Google Cloud. - Nel campo
ENDPOINTS_SERVICE_VERSION
, sostituisci il testo con l'ID configurazione del servizio. Ad esempio:
ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
- Nel campo
- Esegui questo comando:
gcloud app deploy
- Segui le istruzioni sullo schermo. Attendi qualche istante affinché il deployment
sia riuscito, ignorando i messaggi di avviso. Al completamento del deployment, viene visualizzato un messaggio simile al seguente:
File upload done. Updating service [default]...done.
Se hai ricevuto un messaggio di errore, consulta la sezione Risoluzione dei problemi nella documentazione di App Engine per ulteriori informazioni.
Ti consigliamo di attendere alcuni minuti prima di inviare richieste all'API durante l'inizializzazione completa di App Engine.
Invio di una richiesta all'API di esempio
Linux o Mac OS
Invia una richiesta HTTP utilizzando curl
. Sostituisci [YOUR_PROJECT_ID]
con l'ID del tuo
progetto Google Cloud:
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
Nei curl
precedenti:
- L'opzione
--data
consente di specificare i dati da pubblicare nell'API. - L'opzione
--header
specifica che i dati sono in formato JSON.
PowerShell
Invia una richiesta HTTP utilizzando Invoke-WebRequest
. Sostituisci [YOUR_PROJECT_ID]
con l'ID del tuo progetto Google Cloud:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} -URI `
"https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
Nell'esempio precedente, le prime due righe terminano con un accento grave. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo l'accento grave. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.
App di terze parti
Puoi utilizzare un'applicazione di terze parti, ad esempio l'estensione del browser Chrome Postman, per inviare la richiesta:
- Seleziona
POST
come verbo HTTP. - Per l'intestazione, seleziona la chiave
content-type
e il valoreapplication/json
. - Per il corpo, inserisci quanto segue:
{"message":"hello world"}
-
Inserisci l'URL dell'applicazione di esempio. Ad esempio:
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo
L'API restituisce un'eco al messaggio che lo invii e risponde con quanto segue:
{
"message": "hello world"
}
Se non hai ricevuto una risposta corretta, consulta la sezione Risoluzione degli errori di risposta.
monitora l'attività dell'API
Visualizza i grafici di attività per l'API nella console Google Cloud nella pagina Endpoint > Servizio.
Vai alla pagina Endpoints Services
Potrebbero essere necessari alcuni minuti prima che la richiesta venga riportata nei grafici.
Esamina i log delle richieste per l'API nella pagina Esplora log.
Creazione di un portale per gli sviluppatori per l'API
Puoi utilizzare il portale Cloud Endpoints per creare un portale per sviluppatori, un sito web che puoi utilizzare per interagire con l'API di esempio. Per ulteriori informazioni, consulta la pagina Panoramica del portale Cloud Endpoints.
Esegui la pulizia
Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.
- Nella console Google Cloud, vai alla pagina Gestisci risorse.
- Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
- Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.
Passaggi successivi
- Scopri di più sull'architettura di Endpoints Frameworks.
- Scopri di più sulla creazione di un'API.
- Scopri di più sulla creazione di un server web per la pubblicazione dell'API.
- Scopri di più sulla pubblicazione dell'API da un percorso diverso.
- Scopri di più sul monitoraggio dell'API.
- Scopri di più su come limitare l'accesso con le chiavi API.
- Scopri di più sulla configurazione di un nome di dominio personalizzato.
- Scopri di più sulla gestione del controllo delle versioni delle API.
- Scopri le opzioni di assistenza.