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 Ambiente di runtime Python 2.7 standard di App Engine. Endpoints Frameworks è costituito da strumenti, librerie e funzionalità che ti consentono di generare API e librerie client da un ambiente App Engine un'applicazione.
Obiettivi
Durante il tutorial, utilizza il seguente elenco di attività di alto livello. Tutti necessarie per inviare correttamente le richieste all'API.
- Configurare un progetto Google Cloud. Consulta: Prima di iniziare.
- Installa il software richiesto e crea un'applicazione App Engine. Consulta: Installazione e configurazione del software richiesto.
- Scarica il codice campione. Consulta: Recupero del codice campione.
- Genera un documento OpenAPI. Consulta: Configurazione di Endpoints.
- Esegui il deployment della configurazione di Endpoints per creare Servizio Endpoints. Consulta: Esegui il deployment della configurazione di Endpoints.
- Esegui l'esempio sul computer. Consulta: Esecuzione dell'esempio in locale.
- Creare un backend per la gestione dell'API ed il relativo deployment. Consulta: Deployment del backend dell'API.
- Invia una richiesta all'API. Consulta: Invio di una richiesta all'API.
- Monitorare l'attività dell'API. Consulta: Monitoraggio dell'attività dell'API.
- Evita che al tuo account Google Cloud vengano addebitati costi. Consulta: Esegui la pulizia.
Costi
In questo documento utilizzi 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
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- 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 ottenere lo sviluppo standard di App Engine
dell'ambiente di rete. Assicurati di installare
app-engine-python
eapp-engine-python-extras
gcloud
componenti. - Esegui i seguenti comandi:
-
Aggiorna gcloud CLI.
gcloud components update
-
Assicurati che Google Cloud CLI (
gcloud
) sia autorizzato ad accedere i tuoi dati e servizi su Google Cloud:gcloud auth login
- Scegli un account nella nuova scheda del browser che si apre.
-
Imposta il progetto predefinito sul tuo ID progetto.
gcloud config set project [YOUR_PROJECT_ID]
Sostituisci
[YOUR_PROJECT_ID]
con il tuo Google Cloud dell'ID progetto. Se hai altri progetti Google Cloud e vuoi per utilizzaregcloud
per gestirli, consulta Gestione di gcloud CLI configurazioni.
-
Aggiorna gcloud CLI.
-
È necessaria un'applicazione per inviare richieste l'API di esempio.
- Utenti Linux e macOS: questo tutorial fornisce un esempio dell'utilizzo
curl
, che in genere è preinstallata sul sistema operativo. Se non haicurl
, puoi scaricarlo dalcurl
Pagina Release e download. - Utenti Windows: questo tutorial fornisce un esempio di utilizzo
Invoke-WebRequest
, ovvero supportato in PowerShell 3.0 e versioni successive.
- Utenti Linux e macOS: questo tutorial fornisce un esempio dell'utilizzo
- 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 scarica il compilatore Microsoft Visual C++ per Python 2.7 dal Microsoft Centro download .
- Altri sistemi operativi: a seconda del sistema operativo, potrebbe essere necessario
installa 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
su il percorso della cartella dell'SDK di App Engine:[Path-to-Google-Cloud-SDK]/platform/google_appengine
.Sostituisci
[Path-to-Google-Cloud-SDK]
con l'output del seguente comando:gcloud info --format="value(installation.sdk_root)"
- Crea un'applicazione App Engine:
- Seleziona la regione in cui vuoi creare il tuo App Engine
un'applicazione. 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 il tuo Google Cloud con ID progetto e[YOUR_REGION]
con la regione desiderata in cui è stata creata 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 il tuo App Engine
un'applicazione. 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 che contiene il codice campione:
cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Configurazione di Endpoints
Per configurare Endpoints, devi prima installare nella libreria Python di Endpoints Frameworks. Puoi quindi utilizzare uno strumento nella libreria Endpoints Frameworks per generare Documento OpenAPI per l'API di esempio. Devi avere la libreria Endpoints Frameworks e Documento OpenAPI in modo che Endpoints possa gestire l'API. Per ulteriori informazioni informazioni vedi Aggiunta della gestione delle API.
Installazione della libreria Endpoints Frameworks
Questa sezione illustra come utilizzare pip
di Python per aggiungere
la libreria Endpoints Frameworks nella directory del progetto dell'API di esempio.
Per aggiungere la libreria Endpoints Frameworks all'esempio:
Assicurati di trovarti 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
potrebbe utilizzare GNU Compiler Collection (GCC) per compilare moduli di estensione. Se usi macOS ed è la prima volta che usi eseguire GCC sul sistema, è possibile che tu debba accettare la licenza XCode di Apple. A al termine, eseguisudo xcodebuild -license
.Se sul computer sono installate più versioni Python, assicurati stai utilizzando una versione di
pip
corrispondente alla versione Python che stai utilizzando usi in questo tutorial. Mancata corrispondenza delle versioni (pip
da Python 3.4 utilizzandopython
da Python 2.7, ad esempio) può causare errori che possono essere difficili da capire. Se necessario, puoi eseguire pip come Python modulo: 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
. Dopo l'upgrade completato, prova di nuovo a eseguire il comando di installazione.In alcune release Debian e Ubuntu
pip
potrebbe non riuscire con DistutilsOptionError. Se viene visualizzato questo errore, aggiungi il flag --system.
Al completamento, la directory lib
viene compilata con i file
necessario per creare l'applicazione Endpoints Frameworks.
Generazione del documento OpenAPI in corso...
Puoi usare uno strumento della libreria Endpoints Frameworks per generare un documento che descrive l'API REST del codice campione.
Per generare il documento OpenAPI:
Assicurati di trovarti 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. Ignora gli avvisi visualizzati. Lo strumento Endpoints genera un documento OpenAPI denominatoechov1openapi.json
nella directory attuale. Lo strumento Endpoints assegna al file un nome in base al nome del servizio specificato nel decorator@endpoints.api
. Consulta: Creazione dell'API per ulteriori informazioni.Gli endpoint utilizzano il testo specificato nell'argomento
hostname
come nome del servizio. Il formato del nomeYOUR_PROJECT_ID.appspot.com
corrisponde la voce DNS creata automaticamente quando esegui il deployment dell'API il backend di App Engine. Quindi, in questo caso, sia Nome servizio endpoint e nome di dominio completo (FQDN) sono le stesse.
Al termine dell'operazione, 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 e altri servizi per creare e gestire API e servizi.
Per eseguire il deployment del file di configurazione:
- Assicurati di trovarti nella directory principale di esempio:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
- Esegui il deployment del documento OpenAPI generato nella precedente
eseguendo questo comando:
gcloud endpoints services deploy echov1openapi.json
Viene creato un nuovo servizio Endpoints con il nome che specificato nell'argomento
hostname
quando hai eseguito Strumento Endpoints per la generazione del documento OpenAPI. Non importa cosa il nome del servizio Endpoints è quando esegui il deployment dell'API App Engine, viene creato un record DNS utilizzando il formato del nomeYOUR_PROJECT_ID.appspot.com
, ossia il nome di dominio completo da utilizzare quando inviate richieste all'API.Durante la creazione e la configurazione del servizio, Service Management genera un una grande quantità di informazioni al terminale. Puoi ignorare tranquillamente gli avvisi sui percorsi in
echov1openapi.json
che non richiedono una chiave API. Al termine 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
è il servizio eexample-project-12345.appspot.com
è l'ID configurazione il nome del servizio.Vedi
gcloud endpoints services deploy
nel riferimentogcloud
documentazione per ulteriori informazioni.
Controllo dei servizi richiesti in corso...
Per fornire la gestione delle API, Endpoints Frameworks richiede quanto segue Google Cloud: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,
non abilita i servizi richiesti nelle seguenti circostanze:
Se hai utilizzato un'applicazione di terze parti, come Terraform, includono questi servizi.
Hai eseguito il deployment della configurazione di Endpoints in una Progetto Google Cloud in cui questi servizi sono stati disattivati esplicitamente.
Utilizza il comando seguente per confermare che i servizi richiesti siano abilitati:
gcloud services list
Se non vedi elencati i servizi richiesti, 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 il 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 è visualizzato nella colonna Nome servizio.
Per OpenAPI, ENDPOINTS_SERVICE_NAME è quello che hai specificato nel campo
host
della specifica OpenAPI. Per gRPC, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel camponame
della configurazione degli endpoint gRPC.
Per ulteriori informazioni sui comandi gcloud
, consulta
gcloud
servizi.
Esecuzione dell'esempio in locale
Dopo aver eseguito il deployment della configurazione di Endpoints, puoi eseguire locale utilizzando Server di sviluppo locale.
Assicurati di trovarti 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
Nel periodo precedente (curl
):
- 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 in PowerShell, assicuratevi che non ci sia uno spazio dopo l’accento grave. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nel documentazione.
L'API restituisce il messaggio che lo invii e risponde con seguenti:
{
"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 che gestisce il backend dell'API. Questo ti guiderà attraverso la procedura di 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
- Open the
app.yaml
file in thepython-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
directory. - Apporta le seguenti modifiche nella sezione
env_variables
:- Nel campo
ENDPOINTS_SERVICE_NAME
, sostituisciYOUR-PROJECT-ID
con l'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
riuscita, ignorando i messaggi di avviso. Al termine del deployment, verrà visualizzato
simile ai seguenti:
File upload done. Updating service [default]...done.
Se hai ricevuto un messaggio di errore, consulta Risoluzione dei problemi nella documentazione di App Engine per informazioni.
Ti consigliamo di attendere alcuni minuti prima di inviare richieste alla tua API mentre App Engine inizia l'inizializzazione.
- L'opzione
--data
consente di specificare i dati da pubblicare nell'API. - L'opzione
--header
specifica che i dati sono in formato JSON. - 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
Visualizza i grafici di attività per l'API nella console Google Cloud nella Endpoint > Servizio.
Vai alla pagina dei servizi Endpoints
Potrebbero essere necessari alcuni minuti prima che la richiesta venga riportata nei grafici.
Controlla i log delle richieste per l'API nella pagina Esplora log.
Invio di una richiesta all'API di esempio in corso...
Linux o Mac OS
Invia una richiesta HTTP utilizzando curl
. Sostituisci [YOUR_PROJECT_ID]
con
ID 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
Nel periodo precedente (curl
):
PowerShell
Invia una richiesta HTTP utilizzando Invoke-WebRequest
. Sostituisci [YOUR_PROJECT_ID]
con il tuo ID 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 in PowerShell, assicuratevi che non ci sia uno spazio dopo l’accento grave. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nel documentazione.
App di terze parti
Puoi utilizzare un'applicazione di terze parti come il browser Chrome Postman per inviare richiesta:
L'API restituisce il messaggio che lo invii e risponde con seguenti:
{
"message": "hello world"
}
Se non hai ricevuto una risposta positiva, consulta Risoluzione degli errori di risposta.
monitora l'attività dell'API
Creazione di un portale per gli sviluppatori per l'API
Puoi usare il portale Cloud Endpoints per creare un portale per sviluppatori, un sito web che puoi utilizzare per interagire con l'API di esempio. Per saperne di più, vedi 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.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Passaggi successivi
- Informazioni su dell'architettura di Endpoints Frameworks.
- Informazioni su creazione di un'API.
- Informazioni su creazione di un server web per la pubblicazione dell'API.
- Informazioni su la pubblicazione dell'API da un percorso diverso.
- Informazioni su il monitoraggio dell'API.
- Informazioni su limitare l'accesso con chiavi API.
- Informazioni su configurazione di un nome di dominio personalizzato.
- Informazioni su per la gestione del controllo delle versioni dell'API.
- Informazioni su opzioni di assistenza.
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2024-10-25 UTC.