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 Training nelle tue applicazioni Python. I frammenti di codice e gli esempi nel resto della documentazione utilizzano questa libreria client Python.

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 pensato per aiutarti ad acquisire familiarità con questo tramite la libreria client Python. Al termine, dovresti essere in grado di:

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

Costi

Non ti verrà addebitato alcun costo per le operazioni descritte in questo tutorial. 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 un 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. Nel campo Nome account di servizio, inserisci un nome.
    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. Un file della chiave JSON viene scaricato sul computer.
    5. Fai clic su Chiudi.

  3. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS al 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 seguenti per configurare il tuo ambiente localmente su macOS oppure 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 provare AI Platform Training, ma non è adatta per attività di sviluppo continue.

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

    Consulta la documentazione pip per ulteriori informazioni.

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

    pip install --user --upgrade virtualenv

    Per creare un ambiente di sviluppo isolato per questa guida, crea una nuova 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 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

    Una sessione di Cloud Shell si apre all'interno di un nuovo frame nella parte inferiore della console Cloud e visualizza un prompt della riga di comando. L'operazione può richiedere alcuni secondi per inizializzare la sessione di shell.

    Sessione di Cloud Shell

    La sessione di Cloud Shell è pronta per essere utilizzata.

  3. Configura lo strumento a riga di comando gcloud per usare il progetto selezionato. 

    gcloud config set project [selected-project-id]

    dove [selected-project-id] è l'ID progetto. (Ometti tra parentesi quadre che racchiudono il testo.

Installa la libreria client dell'API di Google per Python

Installa la libreria client delle 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 Python dei servizi AI Platform Training.
  • Questa rappresentazione dovrebbe aiutarti a creare un modello nel tuo progetto. capirai come chiamare le altre API di gestione di modelli e job.
Non ti verrà addebitato alcun costo per le operazioni descritte in questo tutorial. Consulta le pagina dei prezzi.

Importazione dei moduli richiesti

Quando vuoi utilizzare la libreria client dell'API di Google per Python per chiamare il metodo API REST AI Platform Training nel codice, devi importare il relativo pacchetto il pacchetto OAuth2. Per questo tutorial (e per la maggior parte degli utilizzi standard AI Platform Training) 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

Recupera la tua 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 il tuo 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 creare 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 dovessi creare la richiesta POST HTTP direttamente, dovresti usare il seguente URI:

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

    Quando si utilizza la libreria client API, la parte variabile dell'URI è rappresentato come parametro di tipo stringa alla chiamata API. Impostalo 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 il modello informazioni. Nella definizione della risorsa del modello puoi vedere che sono presenti due valori per l'input: name e (facoltativo) description. Puoi passare un dizionario Python al posto di JSON e la libreria client API 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 previsti due passaggi: creare una richiesta, quindi effettuare la chiamata utilizzando questa richiesta.

Crea la richiesta

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

Utilizza questo codice per presentare la tua richiesta:

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

Invia la richiesta

La richiesta che hai creato 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. È un una buona idea per gestire 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, incapsulati in il corso HttpError. Per individuare questi errori, userai lo strumento errors dal pacchetto googleapiclient.

Termina la chiamata request.execute() in un blocco try. Aggiungi anche un print l'istruzione di sicurezza nel blocco, in questo modo tenterai di stampare la risposta solo se chiamata riuscita:

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

Aggiungi un blocco 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ù complesse rispetto a la creazione di un modello sì, 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 dei gli 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