Introduzione a Cloud Endpoints Frameworks per Python

---

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 standard Python 2.7 di App Engine. Endpoints Frameworks è costituito da strumenti, librerie e funzionalità che ti consentono di generare API e librerie client da un'applicazione App Engine.

Obiettivi

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

1. Configurare un progetto Google Cloud . Vedi Prima di iniziare.
2. Installa il software richiesto e crea un'applicazione App Engine. Vedi Installazione e configurazione del software richiesto.
3. Scarica il codice campione. Vedi Recupera il codice di esempio.
4. Genera un documento OpenAPI. Consulta Configurazione di Endpoints.
5. Esegui il deployment della configurazione di Endpoints per creare un servizio Endpoints. Vedi Deployment della configurazione di Endpoints.
6. Esegui il campione sul computer. Consulta Esecuzione del campione localmente.
7. Crea un backend per pubblicare l'API ed esegui il deployment dell'API. Consulta Esegui il deployment del backend dell'API.
8. Invia una richiesta all'API. Consulta Invio di una richiesta all'API.
9. Monitora l'attività dell'API. Consulta Monitorare l'attività dell'API.
10. Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.

Costi

In questo documento, utilizzi i seguenti componenti fatturabili di Google Cloud:

• Endpoints
• App Engine

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per ulteriori informazioni, vedi Pulizia.

Prima di iniziare

Nota :assicurati di aver installato Python 2.7.x. Python 3.x non è supportato da Endpoints Frameworks.

1. 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.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

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

Installazione e configurazione del software richiesto

1. Segui le istruzioni riportate in Installazione di Google Cloud CLI per Python per configurare l'ambiente di sviluppo standard di App Engine. Assicurati di installare i componenti app-engine-python e app-engine-python-extras gcloud.
2. Esegui i seguenti comandi:
   1. Aggiorna gcloud CLI.

      gcloud components update

   2. Assicurati che Google Cloud CLI (gcloud) sia autorizzata 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 sull'ID progetto.

      gcloud config set project [YOUR_PROJECT_ID]

      Sostituisci [YOUR_PROJECT_ID] con l'ID progetto Google Cloud. Se hai altri progetti Google Cloud e vuoi utilizzare gcloud per gestirli, consulta Gestione delle configurazioni di gcloud CLI.

3. Per inviare richieste all'API di esempio, devi disporre di un'applicazione.

   • Utenti Linux e macOS: questo tutorial fornisce un esempio di utilizzo di curl, che in genere è preinstallato sul sistema operativo. Se non hai curl, puoi scaricarlo dalla curl pagina di release e download.
   • Utenti Windows: questo tutorial fornisce un esempio che utilizza Invoke-WebRequest, che è supportato in PowerShell 3.0 e versioni successive.
4. Assicurati che il tuo ambiente di sviluppo Python includa pip.
5. 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 del compilatore (a volte in un pacchetto chiamato build-essential) o le intestazioni di sviluppo Python (a volte in un pacchetto chiamato python-dev).

6. 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)"

7. Crea un'applicazione App Engine:
   1. Seleziona la regione in cui vuoi creare l'applicazione App Engine. Esegui questo comando 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 l'ID del tuo progetto Google Cloude [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:

1. Clona il repository di esempio sulla tua macchina locale:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

2. 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 Endpoints Frameworks. Quindi, utilizza uno strumento della libreria Endpoints Frameworks per generare un documento OpenAPI per l'API di esempio. Per consentire a Endpoints di gestire l'API, sono necessari la libreria Endpoints Frameworks e il documento OpenAPI. Per ulteriori informazioni, vedi 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.

Nota: non eseguire Python in un ambiente virtuale. I pacchetti Endpoints Frameworks devono essere installati nella sottodirectory lib della directory del progetto sul computer.

Per aggiungere la libreria Endpoints Frameworks all'esempio:

1. Assicurati di trovarti nella directory principale dell'API di esempio, python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

2. Crea una sottodirectory /lib nel progetto:

   mkdir lib
   

3. 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 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 utilizzi in questo tutorial. Le mancate corrispondenze di versione (ad esempio pip di Python 3.4 durante l'utilizzo di python di Python 2.7) possono causare errori 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 durante l'esecuzione del comando, prova a eseguire l'upgrade eseguendo pip install --upgrade pip. Al termine dell'upgrade, prova di nuovo il comando di installazione.

   • In alcune versioni di Debian e Ubuntu, pip potrebbe non riuscire a causa di DistutilsOptionError. Se visualizzi questo errore, aggiungi il flag --system.

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

Generazione del documento OpenAPI

Utilizzi uno strumento della libreria Endpoints Frameworks per generare un documento che descriva l'API REST del codice campione.

Per generare il documento OpenAPI:

1. Assicurati di trovarti nella directory principale di esempio:

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

2. 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 un nome al file in base al nome e alla versione del servizio specificati nel decoratore @endpoints.api. Per saperne di più, consulta la sezione Creazione dell'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, utilizza 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:

1. Assicurati di trovarti nella directory principale di esempio:

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

2. Esegui il deployment del documento OpenAPI generato nella sezione precedente eseguendo questo comando:

   gcloud endpoints services deploy echov1openapi.json

   In questo modo 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 nome YOUR_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 visualizza molte informazioni nel 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 saperne di più, consulta gcloud endpoints services deploy nella documentazione di riferimento di gcloud.

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

Nella maggior parte dei casi, il comando gcloud endpoints services deploy attiva 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 progettoGoogle Cloud esistente in cui questi servizi sono stati disattivati in modo esplicito.

Utilizza questo comando per verificare che i servizi richiesti siano abilitati:

gcloud services list

Se non vedi i servizi richiesti elencati, 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 il 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 viene visualizzato nella colonna Nome servizio.

• Per OpenAPI, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo host della specifica OpenAPI. Per gRPC, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo name della configurazione di gRPC Endpoints.

Per ulteriori informazioni sui comandi gcloud, consulta servizi gcloud.

Esecuzione del campione in locale

Dopo aver eseguito il deployment della configurazione di Endpoints, puoi eseguire l'esempio localmente utilizzando il server di sviluppo locale.

1. Assicurati di trovarti nella directory principale di esempio:

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

2. 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 stampati da dev_appserver.py: Google Cloud

   INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
   

3. 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 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 accento grave. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo gli apici inversi. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.

L'API restituisce il messaggio che 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 che gestisce il backend dell'API. Questa sezione ti guida nell'esecuzione del deployment dell'API di esempio in App Engine.

Per eseguire il deployment del backend dell'API:

1. 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
   
   

2. 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 l'ID del tuo 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 visualizzate 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 nella documentazione di App Engine per informazioni.

Ti consigliamo di attendere alcuni minuti prima di inviare richieste alla tua 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 l'Google Cloud ID progetto:

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 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

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 gli apici inversi. 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 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 invii e risponde con quanto segue:

{
 "message": "hello world"
}

Se non hai ricevuto una risposta riuscita, consulta la sezione Risoluzione dei problemi relativi agli errori di risposta.

Nota: se vuoi farci sapere cosa ti è piaciuto di questo tutorial, non esitare a fornire un feedback in fondo a questa pagina. Il tuo feedback ci aiuta a migliorare questi tutorial.
Se si è verificato un errore, unisciti al gruppo Google google-cloud-endpoints e comunicaci cosa non ha funzionato. Questo gruppo riceve risposte da altri utenti di Endpoints e dagli ingegneri di Google, che lo monitorano.

monitora l'attività dell'API

1. Visualizza i grafici di attività della tua API nella console Google Cloud nella pagina Endpoints > Servizio.

   Vai alla pagina Servizi endpoint

   La visualizzazione dei dati relativi alla richiesta nei grafici può richiedere alcuni minuti.

2. Esamina i log delle richieste per la tua API nella pagina Esplora log.

   Vai alla pagina Esplora log

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.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:
• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini, elimini anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Passaggi successivi

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