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 Prediction dans vos applications. 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 Prediction ;
  • 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.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

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

    Accéder à la page de sélection du projet

  3. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

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

    Activer les API

  5. Installez et initialisez le SDK Cloud.

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 une clé de compte de service pour l'authentification :
    1. Dans Cloud Console, accédez à la page Créer une clé de compte de service.

      Accéder à la page Créer une clé de compte de service
    2. Dans la liste déroulante Compte de service, sélectionnez Nouveau compte de service.
    3. Dans le champ Nom du compte de service, saisissez un nom.
    4. Dans la liste déroulante Rôle, sélectionnez Machine Learning Engine > Administrateur ML Engine, puis Stockage > Administrateur des objets de l'espace de stockage.

      Remarque : Le champ Rôle autorise votre compte de service à accéder aux ressources. Vous pourrez afficher et modifier ce champ ultérieurement à l'aide de Cloud Console. Si vous développez une application de production, vous devrez peut-être spécifier des autorisations plus précises que Machine Learning Engine > Administrateur ML Engine et Stockage > Administrateur des objets de l'espace de stockage. Pour plus d'informations, consultez la section Contrôle d'accès pour AI Platform Prediction.
    5. Cliquez sur Créer. Un fichier JSON contenant votre clé est téléchargé sur votre ordinateur.
  2. 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). Ce service vous permet d'essayer AI Platform Prediction rapidement. Toutefois, son utilisation n'est pas adaptée 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]

    [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 Prediction ;
  • 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 afin d'appeler les API REST AI Platform Prediction depuis votre code, vous devez importer le package correspondant, ainsi que le package OAuth2. Pour ce tutoriel (et pour la plupart des utilisations standards d'AI Platform Prediction), 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 Prediction est projects. Votre appel commence donc 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 API comme une série d'objets imbriqués pour accéder à l'API souhaitée 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'
    

Étape suivante