Utiliser la bibliothèque cliente Python

Ce tutoriel explique comment utiliser la bibliothèque cliente des API Google pour Python afin d'appeler les API REST AI Platform Training dans vos applications Python. Les extraits de code et les exemples dans cette documentation utilisent la bibliothèque cliente Python.

Au cours de ce tutoriel, vous allez créer un modèle dans votre projet Google Cloud. C'est une tâche simple qu'un petit exemple suffit à expliquer.

Objectifs

Ce tutoriel de base est conçu pour vous permettre de vous familiariser avec cette bibliothèque cliente Python. Une fois le tutoriel terminé, vous devriez être capable :

  • d'obtenir une représentation Python des services AI Platform Training ;
  • de vous servir de cette représentation pour créer un modèle dans votre projet, ce qui vous aidera à comprendre comment appeler les autres API de gestion des modèles et des tâches.

Coûts

Aucuns frais ne vous seront facturés pour les opérations de ce tutoriel. Consultez la page des tarifs pour obtenir plus d'informations.

Avant de commencer

Configurer le projet GCP

  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  4. Activer les API AI Platform Training & Prediction and Compute Engine.

    Activer les API

  5. Installez Google Cloud CLI.

  6. Pour initialiser gcloudCLI, exécutez la commande suivante : 

    gcloud init
    7.

  7. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  8. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  9. Activer les API AI Platform Training & Prediction and Compute Engine.

    Activer les API

  10. Installez Google Cloud CLI.

  11. Pour initialiser gcloudCLI, exécutez la commande suivante : 

    gcloud init
    12.

Configurer l'authentification

Pour configurer l'authentification, vous devez créer une clé de compte de service et définir une variable d'environnement pour le chemin d'accès à la clé de compte de service.

  1. Créez un compte de service :

    1. Dans la console Google Cloud, accédez à la page Créer un compte de service.

      Accéder à la page "Créer un compte de service"

    2. Dans le champ Nom du compte de service, saisissez un nom.
    3. Facultatif : Dans le champ Description du compte de service, saisissez une description.
    4. Cliquez sur Créer.
    5. Cliquez sur le champ Sélectionner un rôle. Sous Tous les rôles, sélectionnez AI Platform > Administrateur AI Platform.
    6. Cliquez sur Ajouter un autre rôle.

    7. Cliquez sur le champ Sélectionner un rôle. Sous Tous les rôles, sélectionnez Stockage > Administrateur des objets de l'espace de stockage.

    8. Cliquez sur Terminé pour créer le compte de service.

      Ne fermez pas la fenêtre de votre navigateur. Vous en aurez besoin lors de la tâche suivante.

  2. Créez une clé de compte de service pour l'authentification :

    1. Dans la console Google Cloud, cliquez sur l'adresse e-mail du compte de service que vous avez créé.
    2. Cliquez sur Keys (Clés).
    3. Cliquez sur AJOUTER UNE CLÉ -> Créer une clé.
    4. Cliquez sur Créer. Un fichier de clé JSON est téléchargé sur votre ordinateur.
    5. Cliquez sur Fermer.

  3. Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS de façon à pointer vers le chemin du fichier JSON contenant la clé de votre compte de service. Cette variable ne s'applique qu'à la session d'interface système actuelle. Par conséquent, si vous ouvrez une nouvelle session, vous devez la définir à nouveau.

Configurer un environnement de développement Python

Choisissez l'une des options ci-dessous pour configurer votre environnement en local sous macOS ou dans un environnement à distance sur Cloud Shell.

Pour les utilisateurs de macOS, nous vous recommandons de configurer votre environnement à l'aide de l'onglet macOS ci-dessous. Cloud Shell est disponible sous macOS, Linux et Windows (voir l'onglet Cloud Shell). Cloud Shell offre un moyen rapide d'essayer AI Platform Training, mais n'est pas adapté aux tâches de développement continu.

macOS

  1. Vérifiez que Python est installé
    Si ce n'est pas le cas, installez Python.

    python -V

  2. Vérifiez que pip est installé
    pip est le gestionnaire de packages de Python, inclus dans les versions actuelles de Python. Vérifiez que pip est déjà installé en exécutant la commande pip --version. Si ce n'est pas le cas, découvrez comment installer pip.

    Vous pouvez mettre à jour pip à l'aide de la commande suivante :

    pip install -U pip

    Pour en savoir plus, consultez la documentation sur pip.

  3. Installez virtualenv
    virtualenv est un outil permettant de créer des environnements Python isolés. Vérifiez que virtualenv est déjà installé en exécutant la commande virtualenv --version. Si ce n'est pas le cas, installez virtualenv : 

    pip install --user --upgrade virtualenv

    Dans ce guide, pour créer un environnement de développement isolé, créez un environnement virtuel dans virtualenv. Par exemple, la commande suivante active un environnement nommé aip-env :

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

  4. Pour les besoins de ce tutoriel, exécutez toutes les autres commandes dans votre environnement virtuel.

    Obtenez plus d'informations sur l'utilisation de virtualenv. Pour quitter virtualenv, exécutez la commande deactivate.

Cloud Shell

  1. Ouvrez Google Cloud Console.

    Google Cloud Console

  2. Cliquez sur le bouton Activer Google Cloud Shell en haut de la fenêtre de la console.

    Activer Google Cloud Shell

    Une session Cloud Shell s'ouvre dans un nouveau cadre en bas de la console et affiche une invite de ligne de commande. L'initialisation de la session Shell peut prendre quelques secondes.

    Session Cloud Shell

    Votre session Cloud Shell est prête à l'emploi.

  3. Configurez l'outil de ligne de commande gcloud pour qu'il utilise le projet sélectionné. 

    gcloud config set project [selected-project-id]

    où [selected-project-id] correspond à votre ID de projet. (Saisissez-le sans les crochets.)

Installer la bibliothèque cliente des API Google pour Python

Installez la bibliothèque cliente des API Google pour Python.

Ce tutoriel de base est conçu pour vous permettre de vous familiariser avec cette bibliothèque cliente Python. Une fois le tutoriel terminé, vous devriez être capable :

  • d'obtenir une représentation Python des services AI Platform Training ;
  • de vous servir de cette représentation pour créer un modèle dans votre projet, ce qui vous aidera à comprendre comment appeler les autres API de gestion des modèles et des tâches.
Aucuns frais ne vous seront facturés pour les opérations de ce tutoriel. Consultez la page des tarifs pour obtenir plus d'informations.

Importer les modules requis

Lorsque vous souhaitez utiliser la bibliothèque cliente des API Google pour Python pour appeler les API REST AI Platform Training dans votre code, vous devez importer son package et le package OAuth2. Pour ce tutoriel (et pour la plupart des utilisations standards de AI Platform Training), il vous suffit d'importer des modules spécifiques :

Consultez la documentation de ces packages pour découvrir les autres modules disponibles.

Créez un fichier Python avec l'éditeur de votre choix, puis ajoutez les lignes suivantes :

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

Construire une représentation Python de l'API

Obtenez votre représentation Python de l'API REST. La méthode que vous appelez est build, car la bibliothèque cliente des API configure dynamiquement les connexions aux services tels qu'ils existent via la détection de services lorsque vous effectuez l'appel. Appelez l'objet qui intègre les services ml :

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

Configurer les paramètres et le corps de la requête

Pour appeler un service, vous devez créer les paramètres et le corps de la requête qui sera transmise à l'API REST. Vous transmettez les paramètres à la méthode qui représente l'appel en tant que paramètres Python usuels. Le corps est une ressource JSON utilisée de la même façon que si vous appeliez directement l'API avec une requête HTTP.

Consultez l'API REST pour créer un modèle dans un nouvel onglet du navigateur, projects.models.create :

  • Notez le paramètre de chemin parent, qui correspond à la partie de l'URI de la requête qui identifie le projet. Pour envoyer la requête HTTP POST directement, par exemple, vous devez utiliser l'URI suivant :

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

    Lors de l'utilisation de la bibliothèque cliente des API, la partie variable de l'URI est représentée en tant que paramètre de type chaîne pour l'appel d'API. Vous devez la définir sur 'projects/<var>YOUR_PROJECT_ID</var>'. Stockez votre projet dans une variable pour simplifier les appels d'API :

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

  • Le corps de la requête est une ressource JSON qui représente les informations du modèle. Dans la définition de la ressource de modèle, vous pouvez voir que celui-ci comporte deux valeurs de saisie : name et (éventuellement) description. Vous pouvez transmettre un dictionnaire Python à la place de la ressource JSON, et la bibliothèque cliente des API effectuera la conversion nécessaire.

    Créez votre dictionnaire Python :

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

Créer votre requête

Les appels d'API avec la bibliothèque cliente Python s'effectuent en deux étapes. Vous créez tout d'abord une requête, puis vous effectuez l'appel à l'aide de cette requête.

Créer la requête

Utilisez les objets clients créés précédemment, si vous avez suivi exactement l'extrait de code ml, en tant que racine de la hiérarchie API et spécifiez l'API à utiliser. Chaque collection dans le chemin de l'API agit comme une fonction qui renvoie une liste des collections et des méthodes qui s'y trouvent. Par exemple, la racine de toutes les API AI Platform Training est projects, donc votre appel commence par ml.projects().

Saisissez ce code pour former votre requête :

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

Envoyer la requête

La requête que vous avez créée lors de la dernière étape expose une méthode execute que vous appelez pour envoyer la requête au service :

response = request.execute()

Généralement, les développeurs regroupent cette étape avec la précédente :

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

Gérer des erreurs simples

Lorsque vous effectuez des appels d'API sur Internet, de nombreuses erreurs peuvent survenir. Il est recommandé de gérer les erreurs courantes. La manière la plus simple de traiter les erreurs consiste à placer votre requête dans un bloc try et à détecter les erreurs probables. La plupart des erreurs que vous êtes susceptible de recevoir du service sont des erreurs HTTP, qui sont encapsulées dans la classe HttpError. Pour détecter ces erreurs, utilisez le module errors à partir du package googleapiclient.

Encapsulez votre appel request.execute() dans un bloc try. Ajoutez également une instruction print dans le bloc, afin d'essayer d'imprimer la réponse uniquement si l'appel aboutit :

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

Enfin, ajoutez un bloc "catch" pour gérer les erreurs HTTP. Vous pouvez utiliser HttpError._get_reason() pour obtenir les champs de texte de la réponse :

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

Bien entendu, une simple instruction d'impression n'est peut-être pas la bonne approche pour votre application.

Synthèse

Voici l'exemple complet :

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

Généraliser pour d'autres méthodes

Vous pouvez suivre la procédure expliquée sur cette page pour effectuer tous les autres appels d'API REST. Des ressources JSON beaucoup plus complexes peuvent être nécessaires pour certaines autres API, mais le principe reste le même :

  1. Importez googleapiclient.discovery et googleapiclient.errors.

  2. Utilisez le module de découverte pour créer une représentation Python de l'API.

  3. Utilisez la représentation de l'API comme une série d'objets imbriqués pour accéder à l'API de votre choix et créer une requête. Par exemple,

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

  4. Appelez request.execute() pour envoyer la requête, en gérant les exceptions de manière appropriée pour votre application.

  5. Lorsqu'il existe un corps dans la réponse, vous pouvez le traiter comme un dictionnaire Python pour obtenir les objets JSON spécifiés dans le document de référence sur les API. Notez que pour de nombreux objets, certains champs ne sont présents que dans certaines circonstances. Vous devriez toujours vérifier les réponses pour éviter les erreurs majeures :

    response = request.execute()

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

Étapes suivantes