Utilizzo della libreria client Python

Questo tutorial descrive come utilizzare la libreria client dell'API di Google per Python per chiamare le API REST AI Platform Prediction nelle tue applicazioni Python. Il codice gli snippet e gli esempi nel resto della documentazione usano questo client Python libreria.

Nel progetto Google Cloud, creerai un modello durante il tutorial. Si tratta di un'attività semplice che può essere facilmente contenuta in un piccolo esempio.

Obiettivi

Questo è un tutorial di base progettato per farti familiarizzare con questa libreria client Python. Al termine, dovresti essere in grado di:

  • Ottieni una rappresentazione in Python dei servizi AI Platform Prediction.
  • Questa rappresentazione dovrebbe aiutarti a creare un modello nel tuo progetto. capirai come chiamare le altre API di gestione di modelli e job.

Costi

Le operazioni in questo tutorial non ti verranno addebitate. Consulta le pagina dei prezzi.

Prima di iniziare

Configura il progetto Google Cloud

  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.

    Go to project selector

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

  4. Enable the AI Platform Training & Prediction and Compute Engine APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

    Go to project selector

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

  9. Enable the AI Platform Training & Prediction and Compute Engine APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

Configura l'autenticazione

Per configurare l'autenticazione, devi creare una chiave dell'account di servizio e impostare una variabile di ambiente per il percorso del file della chiave dell'account di servizio.

  1. Crea un account di servizio:

    1. Nella console Google Cloud, vai alla pagina Crea account di servizio.

      Vai a Crea account di servizio

    2. Inserisci un nome nel campo Nome account di servizio.
    3. (Facoltativo) Nel campo Descrizione account di servizio, inserisci una descrizione.
    4. Fai clic su Crea.
    5. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona AI Platform > Amministratore AI Platform.
    6. Fai clic su Aggiungi un altro ruolo.

    7. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona Spazio di archiviazione > Amministratore oggetti Storage.

    8. Fai clic su Fine per creare l'account di servizio.

      Non chiudere la finestra del browser. Lo utilizzerai nel passaggio successivo.

  2. Crea una chiave dell'account di servizio per l'autenticazione:

    1. Nella console Google Cloud, fai clic sull'indirizzo email dell'account di servizio è stato creato.
    2. Fai clic su Chiavi.
    3. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.
    4. Fai clic su Crea. Sul computer viene scaricato un file della chiave JSON.
    5. Fai clic su Chiudi.

  3. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio. Questa variabile si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.

configura un ambiente di sviluppo Python

Scegli una delle opzioni riportate di seguito per configurare l'ambiente localmente su macOS o in un ambiente remoto su Cloud Shell.

Per gli utenti di macOS, consigliamo di configurare l'ambiente utilizzando MACOS sotto. Cloud Shell, mostrato nella scheda CLOUD SHELL, disponibile su macOS, Linux e Windows. Cloud Shell offre un modo rapido per provare AI Platform Prediction, ma non è adatto per lo sviluppo continuo.

macOS

  1. Controlla l'installazione di Python
    Conferma di avere Python installato e, se necessario, installarlo.

    python -V

  2. Controlla l'installazione di pip
    pip è il gestore di pacchetti di Python, incluso nelle versioni correnti di Python. Per verificare se pip è già installato, esegui pip --version. In caso contrario, scopri come installare pip.

    Puoi eseguire l'upgrade di pip utilizzando il seguente comando:

    pip install -U pip

    Per ulteriori dettagli, consulta la documentazione di pip.

  3. Installa virtualenv
    virtualenv è uno strumento per creare ambienti Python isolati. Per verificare se hai già installato virtualenv, esegui virtualenv --version. In caso contrario, installa virtualenv: 

    pip install --user --upgrade virtualenv

    Per creare un ambiente di sviluppo isolato per questa guida, crea un nuovo ambiente virtuale in virtualenv. Ad esempio, attiva un ambiente denominato aip-env:

    virtualenv aip-env
source aip-env/bin/activate

  4. Ai fini di questo tutorial, esegui gli altri comandi all'interno completamente gestito di Google Cloud.

    Consulta ulteriori informazioni sull'utilizzo di virtualenv. Per uscire da virtualenv, esegui deactivate.

Cloud Shell

  1. Apri la console Google Cloud.

    Console Google Cloud

  2. Fai clic sul pulsante Attiva Google Cloud Shell nella parte superiore della finestra della console.

    Attiva Google Cloud Shell

    All'interno di un nuovo frame nella parte inferiore della console si apre una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Potrebbe essere necessario attendere qualche secondo per l'inizializzazione della sessione della shell.

    Sessione di Cloud Shell

    La sessione Cloud Shell è pronta per l'uso.

  3. Configura lo strumento a riga di comando gcloud in modo da utilizzare il progetto selezionato. 

    gcloud config set project [selected-project-id]

    dove [selected-project-id] è l'ID progetto. (Ometti le parentesi graffe di chiusura.)

Installa la libreria client dell'API di Google per Python

Installa la libreria client dell'API di Google per Python.

Questo è un tutorial di base pensato per aiutarti ad acquisire familiarità con questo tramite la libreria client Python. Al termine, dovresti essere in grado di:

  • Ottieni una rappresentazione in Python dei servizi AI Platform Prediction.
  • Questa rappresentazione dovrebbe aiutarti a creare un modello nel tuo progetto. capirai come chiamare le altre API di gestione di modelli e job.
Le operazioni in questo tutorial non ti verranno addebitate. Consulta le pagina dei prezzi.

Importazione dei moduli richiesti

Quando vuoi utilizzare la libreria client dell'API di Google per Python per chiamare le API REST di AI Platform Prediction nel tuo codice, devi importare il relativo pacchetto e il pacchetto OAuth2. Per questo tutorial (e per la maggior parte degli utilizzi standard AI Platform Prediction) devi importare solo moduli specifici:

Fai riferimento alla documentazione di questi pacchetti per scoprire di più sugli altri pacchetti moduli.

Crea un nuovo file Python utilizzando il tuo editor preferito e aggiungi queste righe:

from oauth2client.client import GoogleCredentials
from googleapiclient import discovery
from googleapiclient import errors

Creazione di una rappresentazione Python dell'API

Ottieni la rappresentazione Python dell'API REST. Il metodo che chiami è build perché la libreria client dell'API utilizza il rilevamento dei servizi per configurare dinamicamente le connessioni ai servizi esistenti al momento della chiamata. Chiama l'oggetto che incapsula i servizi ml:

ml = discovery.build('ml','v1')

Configurare i parametri e il corpo della richiesta

Per effettuare una chiamata a un servizio, devi creare i parametri e il corpo della richiesta che verrà passato all'API REST. Passi i parametri come un normale Python al metodo che rappresenta la chiamata. Il corpo è una risorsa JSON proprio come faresti per chiamare direttamente l'API con una richiesta HTTP.

Dai un'occhiata all'API REST per la creazione di un modello in una nuova scheda del browser, projects.models.create:

  • Nota il parametro del percorso parent, che è la parte dell'URI dell'URL che identifica il progetto. Se inviassi direttamente la richiesta POST HTTP, dovresti utilizzare il seguente URI:

    https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models

    Quando utilizzi la libreria client dell'API, la parte variabile dell'URI viene rappresentata come parametro di tipo stringa per la chiamata all'API. Lo imposti su 'projects/<var>YOUR_PROJECT_ID</var>'. Archivia il progetto in una variabile per rendere più nitide le chiamate API:

    project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

  • Il corpo della richiesta è una risorsa JSON che rappresenta le informazioni del modello. Puoi vedere nel definizione di risorsa modello che abbia due valori per l'input: name e (facoltativamente) description. Puoi passare un dizionario Python al posto di JSON e del client API di Google Cloud eseguirà la conversione necessaria.

    Crea il tuo dizionario Python:

    request_dict = {'name': 'your-model-name',
               'description': 'This is a machine learning model entry.'}

Creazione della richiesta in corso...

Per effettuare chiamate alle API con la libreria client Python sono necessari due passaggi: innanzitutto crei una richiesta, poi effettui la chiamata utilizzandola.

Crea la richiesta

Utilizza gli oggetti client creati in precedenza (se hai seguito esattamente lo snippet di codice, si chiama ml) come radice della gerarchia dell'API e specifica l'API che vuoi utilizzare. Ogni raccolta nel percorso dell'API si comporta come che restituisce un elenco delle raccolte e dei metodi al suo interno. Per Ad esempio, la radice di tutte le API AI Platform Prediction è projects, quindi la chiamata inizia con ml.projects().

Utilizza questo codice per formulare la richiesta:

request = ml.projects().models().create(parent=project_id, body=request_dict)

Invia la richiesta

La richiesta creata nell'ultimo passaggio espone un metodo execute che chiami per inviare la richiesta al servizio:

response = request.execute()

È comune che gli sviluppatori combinino questo passaggio con l'ultimo:

response = ml.projects().models().create(parent=project_id,
                                         body=request_dict).execute()

Gestire errori semplici

Molte cose possono andare storte quando si effettuano chiamate API su internet. È buona prassi gestire gli errori comuni. Il modo più semplice per gestire gli errori è inserisci la tua richiesta in un blocco try e rileva i probabili errori. La maggior parte degli errori che potresti ricevere dal servizio sono errori HTTP, che sono incapsulati nella classe HttpError. Per rilevare questi errori, utilizzerai il modulo errors del pacchetto googleapiclient.

Aggrega la chiamata request.execute() in un blocco try. Inserisci anche un'istruzione print nel blocco, in modo da provare a stampare la risposta solo se la chiamata va a buon fine:

try:
    response = request.execute()
    print(response)

Aggiungi un blocco try/catch per gestire gli errori HTTP. Puoi utilizzare HttpError._get_reason() per recuperare i campi di testo del motivo dalla risposta:

except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Naturalmente, una semplice dichiarazione stampata potrebbe non essere l'approccio giusto per un'applicazione.

Riepilogo

Ecco l'esempio completo:

from googleapiclient import discovery
from googleapiclient import errors

# Store your full project ID in a variable in the format the API needs.
project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

# Build a representation of the Cloud ML API.
ml = discovery.build('ml', 'v1')

# Create a dictionary with the fields from the request body.
request_dict = {'name': 'your_model_name',
               'description': 'your_model_description'}

# Create a request to call projects.models.create.
request = ml.projects().models().create(
              parent=project_id, body=request_dict)

# Make the call.
try:
    response = request.execute()
    print(response)
except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Generalizzazione ad altri metodi

Puoi utilizzare la procedura che hai imparato qui per creare qualsiasi altra API REST chiamate. Alcune API richiedono risorse JSON molto più complicate rispetto alla creazione di un modello, ma i principi sono gli stessi:

  1. Importa googleapiclient.discovery e googleapiclient.errors.

  2. Utilizzare il modulo di rilevamento per creare una rappresentazione Python dell'API.

  3. Utilizza la rappresentazione dell'API come una serie di oggetti nidificati per accedere all'API che ti interessa e creare una richiesta. Ad esempio,

    request = ml.projects().models().versions().delete(
    name='projects/myproject/models/mymodel/versions/myversion')

  4. Chiama request.execute() per inviare la richiesta, gestendo le eccezioni in un modo appropriato per la tua applicazione.

  5. Quando c'è un corpo della risposta, si può trattare come un dizionario Python agli oggetti JSON specificati nel riferimento API. Tieni presente che molti degli oggetti nelle risposte hanno campi presenti solo in alcune circostanze. Devi sempre effettuare dei controlli per evitare errori chiave:

    response = request.execute()

some_value = response.get('some_key') or 'default_value'

Passaggi successivi