Questa pagina è stata tradotta dall'API Cloud Translation.

Introduzione a Cloud Endpoints Frameworks per Python

Questa pagina mostra come configurare, eseguire il deployment e inviare richieste a un'API di esempio utilizzando i framework Cloud Endpoints per Python. Endpoints Frameworks per Python è integrato con l'ambiente di runtime Python 2.7 standard di App Engine. I framework Endpoints sono costituiti da strumenti, librerie e funzionalità che ti consentono di generare API e librerie client da un'applicazione App Engine.

Obiettivi

Segui il seguente elenco di attività di alto livello durante il tutorial. Tutte le attività sono necessarie per inviare correttamente le richieste all'API.

Configurare un progetto Google Cloud. Vedi Prima di iniziare.
Installa il software necessario e crea un'applicazione App Engine. Consulta Installare e configurare il software necessario.
Scarica il codice campione. Consulta Recupero del codice di esempio.
Genera un documento OpenAPI. Consulta Configurare Endpoints.
Esegui il deployment della configurazione di Endpoints per creare un servizio Endpoints. Consulta Eseguire il deployment della configurazione di Endpoints.
Esegui il sample sul computer. Consulta Eseguire l'esempio localmente.
Crea un backend per pubblicare l'API e esegui il deployment dell'API. Consulta Eseguire il deployment del backend dell'API.
Invia una richiesta all'API. Consulta Invio di una richiesta all'API.
Monitora l'attività dell'API. Consulta Monitorare l'attività dell'API.
Evita che al tuo account Google Cloud vengano addebitati costi. Consulta 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. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

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.

Go to project selector

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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Prendi nota dell'ID progetto Google Cloud perché ti servirà in seguito.

Installazione e configurazione del software necessario

Segui le istruzioni riportate in Installazione di Google Cloud CLI per Python per configurare il tuo ambiente di sviluppo standard di App Engine. Assicurati di installare i componenti app-engine-python e app-engine-python-extras gcloud.
Esegui i seguenti comandi:
1. Aggiorna gcloud CLI.
```
gcloud components update
```
2. Assicurati che Google Cloud CLI (gcloud) sia autorizzato ad accedere ai tuoi dati e servizi su Google Cloud:
```
gcloud auth login
```
3. Nella nuova scheda del browser che si apre, scegli un account.
4. Imposta il progetto predefinito sul tuo ID progetto.
```
gcloud config set project [YOUR_PROJECT_ID]
```
  Sostituisci [YOUR_PROJECT_ID] con il tuo ID progetto Google Cloud. Se hai altri progetti Google Cloud e vuoi gestirli con gcloud, consulta Gestire le configurazioni di gcloud CLI.
Devi disporre di un'applicazione per inviare richieste all'API di esempio.
- Utenti Linux e macOS: questo tutorial fornisce un esempio di utilizzo di curl, che in genere è preinstallato nel sistema operativo. Se non hai curl, puoi scaricarlo dalla curl pagina Release e download.
- Utenti Windows: questo tutorial fornisce un esempio di utilizzo di Invoke-WebRequest, supportato in PowerShell 3.0 e versioni successive.
Assicurati che l'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 di download di Microsoft .
- Altri sistemi operativi: a seconda del sistema operativo, potrebbe essere necessario installare gli strumenti di compilatore (a volte in un pacchetto denominato build-essential) o gli header di sviluppo Python (a volte in un pacchetto denominato python-dev).
Per Linux, imposta la variabile di ambiente ENDPOINTS_GAE_SDK sul 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:
1. Seleziona la regione in cui vuoi creare l'applicazione App Engine. Esegui il comando seguente per ottenere un elenco di regioni:
```
gcloud app regions list
```
2. Crea un'applicazione App Engine utilizzando il seguente comando. Sostituisci [YOUR_PROJECT_ID] con il tuo 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
```

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 la libreria Python Endpoints Frameworks. Poi utilizzi uno strumento della libreria Endpoints Frameworks per generare un documento OpenAPI per l'API di esempio. Per consentire a Endpoints di gestire l'API, devi disporre della libreria Endpoints Frameworks e del documento OpenAPI. Per ulteriori informazioni, consulta Aggiunta della gestione API.

Installazione della libreria Endpoints Frameworks

Questa sezione illustra come utilizzare pip di Python per aggiungere la libreria Endpoints Frameworks alla directory del progetto dell'API di esempio.

Per aggiungere la libreria Endpoints Frameworks al sample:

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 dell'esempiopython-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 i moduli di estensione. Se utilizzi macOS ed è la prima volta che esegui GCC sul tuo sistema, potresti dover accettare la licenza XCode di Apple. Per farlo, esegui sudo xcodebuild -license.
- Se sul computer sono installate più versioni di Python, assicurati di utilizzare una versione di pip corrispondente alla versione di Python che stai utilizzando in questo tutorial. Le mancate corrispondenze delle versioni (pip da Python 3.4 mentre si utilizza python da Python 2.7, ad esempio) possono causare errori che possono essere difficili da comprendere. Se necessario, puoi eseguire pip come modulo Python: sostituisci pip nel comando precedente con python -m pip.
- Se pip non riesce a trovare un pacchetto adatto quando esegui il comando, prova a eseguirne l'upgrade eseguendo pip install --upgrade pip. Al termine dell'upgrade, riprova a eseguire il comando di installazione.
- In alcune release di Debian e Ubuntu, pip potrebbe non riuscire con DistutilsOptionError. Se visualizzi questo errore, aggiungi il flag --system.

Al termine, la directory lib viene compilata con i file necessari per compilare l'applicazione Endpoints Frameworks.

Generazione del documento OpenAPI

Utilizza uno strumento della libreria 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 dell'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 denominato echov1openapi.json nella directory corrente. Lo strumento Endpoints assegna il nome al file in base al nome e alla versione del servizio specificati nel decoratore @endpoints.api. Per ulteriori informazioni, consulta la sezione Creare l'API.

Endpoints utilizza il testo specificato nell'argomento hostname come nome del servizio. Il formato del nome YOUR_PROJECT_ID.appspot.com corrisponde alla voce DNS creata automaticamente quando esegui il deployment dell'API nel backend di App Engine. In questo caso, sia il nome del servizio Endpoints sia il nome di dominio completo (FQDN) sono uguali.

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, utilizzi Service Infrastructure, la piattaforma di servizi di base di Google, utilizzata da Endpoints e da altri servizi per creare e gestire API e servizi.

Per eseguire il deployment del file di configurazione:

Assicurati di essere nella directory principale dell'esempio:

python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo

Esegui il deployment del documento OpenAPI generato nella sezione precedente eseguendo il seguente 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 Endpoints 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 FQDN che utilizzi quando invii richieste all'API.

Durante la creazione e la configurazione del servizio, Service Management visualizza moltissime informazioni sul terminale. Puoi ignorare tranquillamente gli avvisi sui percorsi presenti 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 è l'ID configurazione del servizio e example-project-12345.appspot.com è il nome del servizio.

Per ulteriori informazioni, consulta gcloud endpoints services deploy nella documentazione di riferimentogcloud.

Verifica 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

Nella maggior parte dei casi, il comando gcloud endpoints services deploy attiva questi servizi obbligatori. Tuttavia, il comando gcloud viene completato correttamente, ma non attiva 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 disattivati esplicitamente.

Utilizza il seguente comando per verificare che i servizi richiesti siano abilitati:

gcloud services list

Se non vedi i servizi richiesti nell'elenco, attivali:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.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 Endpoints nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è riportato nella colonna Nome servizio.
Per OpenAPI, ENDPOINTS_SERVICE_NAME è il valore specificato nel campo host della specifica OpenAPI. Per gRPC, ENDPOINTS_SERVICE_NAME è il valore specificato nel campo name della configurazione degli endpoint gRPC.

Per ulteriori informazioni sui comandi gcloud, consulta Servizi gcloud.

Eseguire il sample localmente

Dopo aver eseguito il deployment della configurazione degli endpoint, puoi eseguire il sample localmente utilizzando il server di sviluppo locale.

Assicurati di essere nella directory principale dell'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 è in ascolto su http://localhost:8080, come indicato nei log della console Google Cloud stampati da dev_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 curl precedente:

L'opzione --data specifica 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 backtick. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo i backtick. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.

L'API restituisce il messaggio che le hai inviato e risponde con quanto segue:

{
 "message": "hello world"
}

esegui il deployment del backend dell'API

Fino a questo punto, hai eseguito il deployment del documento OpenAPI in Service Management, ma non hai ancora eseguito il deployment del codice soggiacente al backend dell'API. Questa sezione illustra la procedura per eseguire il deployment dell'API di esempio in App Engine.

Per eseguire il deployment del backend dell'API:

Visualizza l'ID configurazione del servizio eseguendo il seguente 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 the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.

env_variables:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy swagger.json' command.
  ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
  ENDPOINTS_SERVICE_VERSION: 2016-08-01r0

Apporta le seguenti modifiche nella sezione env_variables:

Nel campo ENDPOINTS_SERVICE_NAME, sostituisci YOUR-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

Esegui questo comando:

gcloud app deploy

Segui le istruzioni sullo schermo. Attendi qualche istante per il completamento 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.

Se hai ricevuto un messaggio di errore, consulta la sezione Risoluzione dei problemi della documentazione di App Engine per ulteriori informazioni.

Ti consigliamo di attendere alcuni minuti prima di inviare richieste all'API mentre App Engine si inizializza completamente.

Invio di una richiesta all'API di esempio

Linux o Mac OS

Invia una richiesta HTTP utilizzando curl. Sostituisci [YOUR_PROJECT_ID] con il tuo 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 curl precedente:

L'opzione --data specifica 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

App di terze parti

Puoi utilizzare un'applicazione di terze parti come 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 valore application/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 il messaggio che le hai inviato e risponde con quanto segue:

{
 "message": "hello world"
}

Se non hai ricevuto una risposta positiva, consulta Risolvere i problemi relativi alle risposte.

monitora l'attività dell'API

Visualizza i grafici delle attività della tua API nella console Google Cloud nella pagina Endpoints > Service.

Vai alla pagina Servizi endpoint

La visualizzazione dei dati relativi alla richiesta nei grafici può richiedere alcuni minuti.
Esamina i log delle richieste per la tua API nella pagina Esplora log.

Vai alla pagina Esplora log

Creazione di un portale per gli sviluppatori per l'API

Puoi utilizzare il portale Cloud Endpoints per creare un portale per gli sviluppatori, un sito web che puoi utilizzare per interagire con l'API di esempio. Per saperne di più, consulta la 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.
Go to Manage resources
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

Scopri di più sull'architettura dei framework Endpoints.
Scopri di più sulla creazione di un'API.
Scopri come creare un server web per pubblicare la tua API.
Scopri come pubblicare l'API da un percorso diverso.
Scopri di più sul monitoraggio dell'API.
Scopri di più sulla limitazione dell'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 dell'API.
Scopri di più sulle opzioni di assistenza.