Appeler des API depuis un projet Google Cloud

1. Avant de commencer

Cet atelier de programmation vous montre comment créer un projet Google Cloud, puis comment appeler les API Google Cloud à partir de ce projet.

Prérequis

• Vous devez savoir parcourir la console Google Cloud.

Points abordés

• Découvrez comment créer un projet Google Cloud.
• Configurer un compte de facturation
• Configurer Cloud Shell
• Comment activer une API ?
• Comment autoriser une API avec une clé API
• Autoriser une API avec un compte de service

Prérequis

• Un compte Google, tel qu'un compte Gmail ou un compte Google Workspace.
• Accès à un compte de facturation Cloud ou à une carte de crédit à utiliser pour s'inscrire au programme d'essai sans frais.

2. Configuration

Cette section vous explique comment créer un projet Google Cloud, configurer un compte de facturation et configurer Cloud Shell.

Créer un projet Google Cloud et configurer un compte de facturation

Remarque : Si vous ne possédez pas encore de compte Gmail ni de compte Google Workspace, vous devez d'abord en créer un.

1. Connectez-vous à la console Cloud, puis sélectionnez ou créez un projet.

Avertissement : Si vous réutilisez un projet et que vous suivez cet atelier de programmation, vous pouvez autoriser certains utilisateurs à accéder aux ressources de ce projet si elles ne sont pas désactivées à la fin de l'atelier.

Retenez l'ID du projet, affiché au-dessous du champ Nom du projet. Il s'agit d'un nom unique pour tous les projets Google Cloud (le nom ci-dessus est déjà pris). Il est désigné par PROJECT_ID dans cet atelier de programmation.

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte Google Workspace, choisissez un emplacement qui ait du sens pour votre organisation.

2. Ensuite, activez la facturation dans la console Cloud pour pouvoir utiliser les ressources Google Cloud.

Bien que cet atelier de programmation ne devrait pas vous coûter cher, voire rien du tout, suivez les instructions de la section Nettoyer pour arrêter les ressources et éviter des frais supplémentaires. Notez que les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais pour un crédit de 300$.

Configurer Cloud Shell

Dans cet atelier de programmation, vous allez utiliser Cloud Shell, un environnement de ligne de commande qui s'exécute dans Google Cloud. Cloud Shell est une machine virtuelle basée sur Debian qui contient tous les outils de développement dont vous avez besoin. Elle comprend un répertoire d'accueil persistant de 5 Go, ce qui améliore nettement les performances du réseau et l'authentification. Cela signifie que tout ce dont vous avez besoin pour cet atelier de programmation est un navigateur.

Pour activer Cloud Shell à partir de la console Cloud :

1. Cliquez sur Activer Cloud Shell.

Le provisionnement et la connexion à l'environnement peuvent prendre quelques instants.

Une fois connecté à Cloud Shell, vous êtes normalement déjà authentifié et le projet PROJECT_ID est sélectionné :

2. Générez une liste des comptes avec des identifiants :

gcloud auth list

Vous devriez obtenir le résultat suivant :

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

Remarque : L'outil CLI gcloud est préinstallé dans Cloud Shell et vous aide à créer et à gérer des ressources Google Cloud. Pour en savoir plus, consultez la présentation de l'outil gcloud.

3. Pour afficher la liste de vos projets, saisissez cette commande.

gcloud config list project

Vous devriez obtenir le résultat suivant :

[core]
project = <PROJECT_ID>

Si, pour une raison quelconque, le projet n'est pas défini, exécutez cette commande pour le configurer.

gcloud config set project <PROJECT_ID>

PROJECT_ID correspond à l'ID que vous avez utilisé lors de la procédure de configuration. Vous pouvez également le rechercher dans le tableau de bord de la console Cloud :

Par défaut, Cloud Shell définit certaines variables d'environnement qui pourront s'avérer utiles pour exécuter certaines commandes dans le futur.

4. Pour afficher l'ID de votre projet, saisissez la commande suivante.

echo $GOOGLE_CLOUD_PROJECT

Vous devriez obtenir le résultat suivant :

<PROJECT_ID>

5. Pour finir, définissez la configuration du projet et de la zone par défaut :

gcloud config set compute/zone us-central1-f

Vous pouvez choisir parmi différentes zones. Pour en savoir plus, consultez Régions et zones.

Remarque : Lorsque vous exécutez l'outil CLI gcloud sur votre machine, les paramètres de configuration sont conservés d'une session à l'autre. En revanche, dans Cloud Shell, vous devez configurer ces paramètres à chaque nouvelle session ou reconnexion.

3. Appeler une API depuis un projet

Cet atelier de programmation vous montre comment utiliser un exemple d'API (l'API Natural Language) pour trouver des entités (comme des personnes, des lieux et des événements) dans un texte, et comment évaluer approximativement le sentiment (le niveau de favorabilité) de ce texte. Vous allez apprendre à :

• Activez les API Google Cloud.
• Obtenez l'autorisation d'accéder à l'API à l'aide de clés API et de comptes de service.
• Appelez l'API avec curl et les bibliothèques clientes.

Activer une API

1. Sélectionnez API et services dans le menu principal de la console Cloud.

2. Sélectionnez + ACTIVER DES API ET DES SERVICES en haut de l'écran.

3. À ce stade, vous pouvez filtrer et parcourir les API, ou accéder directement à une API à l'aide du champ Rechercher. Recherchez Natural Language et sélectionnez API Cloud Natural Language.

4. Cliquez sur ESSAYER CETTE API.

Si le bouton TRY THIS API (Essayer cette API) ne s'affiche pas, cliquez sur l'une des méthodes listées pour l'essayer.

Créer une clé API

Étant donné que vous utilisez curl pour envoyer une requête à l'API Natural Language, vous devez générer une clé API afin de transmettre l'URL de la requête.

1. Dans la console Cloud, sélectionnez Menu de navigation > API et services > Identifiants.

2. Cliquez sur CRÉER DES IDENTIFIANTS, puis sélectionnez Clé API :

3. Copiez la clé API générée, puis cliquez sur Fermer.

Utiliser la clé API pour appeler l'API

1. Dans la ligne de commande Cloud Shell, exportez votre clé API.

export API_KEY=<YOUR_API_KEY>

Remplacez <YOUR_API_KEY> par la clé que vous avez générée précédemment.

2. Créez une requête pour l'API dans l'éditeur Cloud Shell ou avec un éditeur Linux, tel que Vim ou Emacs. Vous trouverez les détails des paramètres sur la page Méthode : documents.analyzeEntities. Enregistrez le résultat dans un fichier nommé request.json :

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}

3. Appelez l'API avec les informations de la requête.

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. Réexécutez la commande, redirigez la sortie vers un fichier et examinez le résultat. Les détails de la sortie du fichier JSON sont également disponibles dans Méthode : documents.analyzeEntities.
5. Pour modifier le texte à analyser dans le fichier request.json, remplacez la valeur content par le texte de votre choix.

4. Autoriser avec un compte de service

Les comptes de service sont souvent préférés aux clés API, car ils fournissent à la fois l'authentification et l'autorisation. Vous pouvez considérer les comptes de service comme des adresses e-mail pour votre application.

1. Revenez à la section "Identifiants" du menu API et services.
2. Sélectionnez Créer des identifiants, mais cette fois, sélectionnez Compte de service.

3. Indiquez un nom de compte de service qui décrit son objectif, par exemple "Natural Language Service Account". Le système suggère un ID. Vous pouvez également ajouter une description. À mesure que vous en apprendrez davantage sur les comptes de service, vous pourrez leur accorder l'accès à des projets et accorder aux utilisateurs l'accès au compte de service. Pour l'instant, cliquez simplement sur OK pour créer le compte de service.
4. Pour créer une paire de clés à utiliser pour le compte de service, cliquez sur  pour modifier le compte de service.

Les détails de votre compte de service s'affichent.

5. Copiez l'adresse e-mail du compte de service, puis revenez à Cloud Shell.
6. Dans Cloud Shell, créez une paire de clés pour votre compte de service et définissez une variable d'environnement pour y pointer :

gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

Google Cloud utilise cette variable d'environnement pour trouver les identifiants. Il n'est donc pas nécessaire de les inclure dans l'appel d'API.

7. Vous pouvez maintenant appeler l'API avec la commande suivante :

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

Le résultat doit être identique à celui obtenu précédemment.

De nombreuses API disposent de bibliothèques clientes complètes pour extraire ces informations. Pour en savoir plus sur les bibliothèques clientes, consultez Bibliothèques clientes Cloud. Vous pouvez également consulter la documentation des API que vous utilisez pour voir quelles bibliothèques clientes sont disponibles.

5. Effectuer un nettoyage

Il est déconseillé d'utiliser une clé API sans restriction pour les projets. Si une personne y a accès, elle peut l'utiliser sans avoir besoin de s'authentifier.

Pour supprimer cette clé API :

1. Cliquez sur  Menu de navigation > API et services > Identifiants.
2. Sous Clés API, sélectionnez la clé à supprimer, puis cliquez sur Supprimer.
3. De même, plutôt que de vous inquiéter de la protection de la clé privée de votre compte de service, sous Comptes de service, sélectionnez le compte de service à supprimer, puis cliquez sur Supprimer.

6. Félicitations

Félicitations ! Vous avez appris à créer un projet Google Cloud et à appeler une API depuis ce projet.