Optimisez votre boîte de réception Gmail avec Google Cloud Functions

1. Introduction

Des milliards d'entreprises et de particuliers utilisent Gmail et d'autres services G Suite pour communiquer et traiter des données. Google propose des API G Suite pour vous aider à accéder aux informations de ces services de manière programmatique. Vous pouvez utiliser ces API pour automatiser facilement votre workflow quotidien. Dans cet atelier, vous allez créer une extension Gmail puissante qui catégorise automatiquement les e-mails dans les messages entrants et enregistre ces catégories dans une feuille de calcul Google. Cette extension utilisera les API RESTful de G Suite, Google Cloud Functions et d'autres services Google Cloud Platform.

Objectifs de l'atelier

Dans cet atelier, vous allez créer et déployer quelques fonctions Cloud Functions connectées aux API G Suite et à d'autres services Google Cloud Platform. Ces fonctions :

Autoriser un accès sécurisé à vos données Gmail et Google Sheets
Extraire les images jointes à tous les e-mails entrants
Catégoriser ces images à l'aide de l'API Cloud Vision
Écrivez ces catégories, l'adresse de l'expéditeur et le nom de la pièce jointe dans une feuille de calcul Google Sheets.

Objectifs de l'atelier

Principes de base des API RESTful G Suite
Principes de base de Google Cloud Functions et des autres services Google Cloud Platform
Accéder à Gmail de manière programmatique à l'aide de Google Cloud Functions

Ce dont vous avez besoin

Un compte Google avec accès à Gmail et Google Sheets Si vous n'en avez pas, créez-en un ici.
Connaissances de base en JavaScript/Node.js

2. Avant toute chose

Activer les API

Dans cet atelier, vous allez utiliser les produits et services Google suivants :

Google Cloud Functions
Google Cloud Pub/Sub
Google Cloud Vision API
Google Cloud Datastore
API Gmail
API Google Sheets

Google Cloud Functions

Google Cloud Functions est la plate-forme FaaS (Functions-as-a-Service) sans serveur de Google qui vous permet d'exécuter des extraits de code individuels ("fonctions") de manière simple et évolutive.

Pour activer Google Cloud Functions, cliquez sur le menu hamburger en haut à gauche de l'écran pour ouvrir la barre de navigation de gauche :

Recherchez Cloud Functions dans le menu de navigation, puis cliquez dessus. Cliquez sur Activer l'API pour activer Google Cloud Functions dans votre projet.

Google Cloud Pub/Sub

Google Cloud Pub/Sub est une base simple et évolutive pour le streaming de données et la diffusion d'événements. Dans cet atelier, il sert de messager entre Gmail et Google Cloud Functions.

Pour activer Google Cloud Pub/Sub, ouvrez la barre de navigation de gauche, recherchez Pub/Sub, puis cliquez dessus. Cliquez sur Activer l'API pour activer Google Cloud Pub/Sub dans votre projet.

Google Cloud Datastore

Google Cloud Datastore est une base de données sans serveur, évolutive et distribuée.

Pour activer Google Cloud Datastore, recherchez Datastore dans la barre de navigation de gauche, puis cliquez dessus. Sur la nouvelle page, cliquez sur Sélectionner le mode Datastore.

Vous pouvez utiliser n'importe quel emplacement de base de données pour cet atelier. Cliquez sur Créer une base de données pour activer Google Cloud Datastore. Cette opération peut prendre quelques minutes.

Google Cloud Vision

L'API Google Cloud Vision est un service de machine learning puissant qui utilise des modèles pré-entraînés pour obtenir des insights à partir de vos images.

Consultez les instructions ci-dessous pour savoir comment activer l'API Google Cloud Vision.

Activer les API Gmail, Google Sheets et Google Cloud Vision

Ouvrez à nouveau la barre de navigation de gauche et recherchez API et services. Cliquez sur Bibliothèque. Dans le champ Rechercher des API et des services, saisissez Gmail. Dans les résultats de recherche, sélectionnez Gmail API (API Gmail), puis cliquez sur Enable (Activer).

Revenez à la page "Bibliothèque d'API". Recherchez l'API Google Sheets et activez-la.

Répétez le processus. Recherchez l'API Cloud Vision et activez-la.

Ouvrir Google Cloud Shell

Dans cet atelier, vous allez utiliser Google Cloud Shell pour effectuer la plupart des opérations. Cloud Shell vous permet d'accéder en ligne de commande à vos ressources Google Cloud Platform directement depuis votre navigateur, ce qui vous permet de les gérer sans utiliser de machine locale.

Pour ouvrir Google Cloud Shell, cliquez sur le bouton Activer Cloud Shell dans la barre horizontale bleue en haut de la page :

Un nouveau panneau s'affiche en bas de l'écran :

Cliquez sur le bouton Lancer l'éditeur de code pour démarrer l'éditeur de code Cloud Shell :

L'éditeur de code Cloud Shell s'ouvre dans une nouvelle fenêtre.

Télécharger le code

Exécutez la commande ci-dessous dans Cloud Shell pour cloner le projet :

git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git

cd gcf-gmail-codelab

Un nouveau dossier, gcf-gmail-codelab, devrait apparaître dans l'éditeur de code Cloud Shell.

3. Présentation de l'architecture

Voici le workflow de cet atelier :

L'utilisateur configure les notifications push Gmail : chaque fois qu'un nouveau message arrive dans la boîte de réception, Gmail envoie une notification à Cloud Pub/Sub.
Cloud Pub/Sub envoie la notification de nouveau message à Google Cloud Functions.
Lorsqu'une notification de nouveau message arrive, une instance Cloud Functions se connecte à Gmail et récupère le nouveau message.
Si le mail contient une image en pièce jointe, l'instance Cloud Functions appelle l'API Cloud Vision pour analyser la pièce jointe.
L'instance Cloud Functions met à jour la feuille de calcul Google Sheets de votre choix, en précisant qui a envoyé le message et où télécharger la pièce jointe.

4. Autoriser l'accès à Gmail

Avant de configurer une fonction Cloud pour lire automatiquement vos e-mails, vous devez autoriser son accès à Gmail. Vous devrez enregistrer un client OAuth auprès de Google et créer un ID client associé.

Enregistrer un client OAuth

Dans le menu de navigation de gauche de la console Google Cloud, recherchez API et services. Cliquez sur Écran d'autorisation OAuth.

Saisissez un nom dans le champ Nom de l'application, par exemple Atelier de programmation GCF + Gmail. Laissez les autres paramètres tels quels, faites défiler la page vers le bas, puis cliquez sur Enregistrer.

Créer un ID client associé

Accédez à l'onglet Identifiants. Cliquez sur Créer des identifiants, puis sélectionnez ID client OAuth. Sélectionnez le type Application Web, donnez-lui un nom (vous pouvez réutiliser Atelier de programmation GCF + Gmail), puis cliquez sur Créer. Laissez les champs "Restrictions" vides pour le moment.

Notez l'ID client et le code secret du client renvoyés dans la fenêtre pop-up. Vous pouvez cliquer sur le nom de votre client sur la page pour afficher à nouveau ces valeurs :

Effectuer le processus d'autorisation

Dans l'exemple de code, auth/index.js spécifie deux fonctions Cloud Functions, auth_init et auth_callback, qui fonctionnent ensemble pour effectuer le processus d'autorisation, en utilisant l'ID client et le secret client que vous venez de créer.

Pour inspecter le code, ouvrez auth/index.js dans l'éditeur de code Cloud Shell.

Le processus d'autorisation renvoie deux types de jetons : les jetons d'accès et les jetons d'actualisation.

Les jetons d'accès sont des preuves d'identité de courte durée qui accordent à toute personne qui les possède un accès limité à vos données. auth_callback les enregistre dans Cloud Datastore.
Les jetons d'actualisation permettent d'obtenir de nouveaux jetons d'accès et ont une durée de vie beaucoup plus longue.

En règle générale, ils sont chiffrés et/ou stockés séparément des jetons d'accès.

Modifiez auth/env_vars.yaml dans l'éditeur de code Cloud Shell. Remplacez YOUR-GOOGLE-CLIENT-ID et YOUR-GOOGLE-CLIENT-SECRET par vos propres valeurs. Pour en savoir plus, consultez l'étape précédente. Pour l'instant, ne modifiez pas les valeurs de YOUR-GOOGLE-CLIENT-CALLBACK-URL et YOUR-PUBSUB-TOPIC.

Après avoir modifié auth/env_vars.yaml, exécutez la commande suivante dans Cloud Shell pour déployer les fonctions Cloud :

cd ~
cd gcf-gmail-codelab/auth

# Deploy Cloud Function auth_init
gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

# Deploy Cloud Function auth_callback
gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

Le déploiement des fonctions Cloud peut prendre quelques minutes. Si vous y êtes invité, autorisez le SDK Cloud à installer les commandes bêta.

Ensuite, accédez à la console Google Cloud et cliquez sur Cloud Functions dans le menu de navigation de gauche. Cliquez sur auth_callback dans la liste des fonctions Cloud, puis passez à l'onglet Déclencheur.

Copiez l'URL de la page. Revenez à la page Cloud Functions, puis cliquez sur auth_init dans la liste des fonctions Cloud. Dans l'onglet Général, cliquez sur Modifier. Cliquez sur Variables d'environnement, mise en réseau, délais avant expiration, etc., puis remplacez la valeur de GOOGLE_CALLBACK_URL par l'URL que vous venez de copier.

Cliquez sur Déployer pour appliquer les modifications. Répétez le processus et mettez également à jour auth_callback.

Enfin, ouvrez le menu de navigation de gauche et cliquez sur API et services > Validation du domaine. Pour ajouter un domaine autorisé, cliquez sur Ajouter un domaine. Par exemple, si l'URL que vous avez copiée précédemment ressemble à

https://us-central1-my-project.cloudfunctions.net/auth_callback

Vous devez ajouter les éléments suivants en tant que domaine autorisé :

us-central1-my-project.cloudfunctions.net

Appuyez sur Ajouter un domaine pour confirmer.

Revenez à la page Identifiants. Cliquez sur le nom de votre client OAuth et ajoutez l'URL que vous avez copiée en tant qu'URI de redirection autorisé. Appuyez sur Entrée pour confirmer.

Supprimez la partie /auth_callback de l'URL et ajoutez le reste en tant qu'origine JavaScript autorisée. Par exemple, si votre URL ressemble à

https://us-central1-my-project.cloudfunctions.net/auth_callback

Vous devez ajouter l'origine suivante :

https://us-central1-my-project.cloudfunctions.net/

Appuyez sur Entrée pour confirmer, puis cliquez sur Enregistrer pour appliquer les modifications.

5. Configurer les notifications push Gmail

Si le processus d'autorisation aboutit, auth_callback appellera automatiquement l'API Gmail pour configurer les notifications push.

Pour recevoir des notifications push Gmail, vous devez créer un sujet Pub/Sub. Tout abonné à la discussion recevra automatiquement des notifications pour les nouveaux messages Gmail.

Pour créer un sujet Pub/Sub, accédez à la console Google Cloud et cliquez sur Pub/Sub > Sujets dans le menu de navigation de gauche. Cliquez sur Créer un sujet. Saisissez le nom du thème, par exemple gmail-watch, puis cliquez sur Créer. Vous devez également autoriser Gmail à envoyer des messages à votre sujet Pub/Sub : cliquez sur le menu contextuel du sujet que vous venez de créer (trois points verticaux), puis sélectionnez Autorisations. Cliquez sur Ajouter des membres, spécifiez gmail-api-push@system.gserviceaccount.com comme nouveau membre, puis attribuez-lui le rôle Pub/Sub > Éditeur Pub/Sub. Enfin, cliquez sur Enregistrer pour appliquer les modifications.

Mettez à jour la fonction Cloud auth_callback pour spécifier le sujet Pub/Sub à utiliser. Cliquez sur Cloud Functions dans le menu de navigation de gauche, puis sélectionnez auth_callback dans la liste des fonctions Cloud. Dans l'onglet Général, cliquez sur Modifier. Cliquez sur Plus, puis remplacez la valeur de PUBSUB_TOPIC par le nom du sujet Pub/Sub que vous venez de créer. Cliquez sur Enregistrer pour appliquer les modifications.

Vous êtes maintenant prêt à autoriser et à configurer les notifications push Gmail. Attendez que les nouvelles modifications soient finalisées, puis revenez à la page Cloud Functions, sélectionnez auth_init dans la liste des fonctions Cloud, puis passez à l'onglet Déclencheur. Cliquez sur l'URL pour être redirigé vers la page Se connecter avec Google :

Connectez-vous avec un compte Gmail qui vous appartient. Tout nouveau message reçu dans la boîte de réception du compte déclenchera une notification push. Une fois connecté, la page ci-dessous s'affiche :

Cliquez sur Autoriser pour autoriser l'accès. auth_callback effectuera le processus d'autorisation, enregistrera les jetons d'accès et configurera les notifications push Gmail pour vous. Une fois le processus terminé, le message Successfully set up Gmail push notifications s'affiche dans votre navigateur.

Cet atelier de programmation utilise le package @google-cloud/express-oauth2-handlers pour automatiser le workflow d'autorisation. Pour en savoir plus, consultez son dépôt sur GitHub.

6. Traiter les messages entrants

Comme nous l'avons mentionné précédemment, tous les abonnés au sujet Pub/Sub que vous avez créé recevront des notifications lorsque de nouveaux messages arriveront dans votre boîte de réception. pubsub/index.js spécifie une fonction Cloud, watchGmailMessages, qui, une fois déployée en tant qu'abonné au sujet, lira les nouveaux messages, catégorisera les images jointes et exportera ces catégories vers une feuille de calcul Google.

Pour inspecter le code, ouvrez pubsub/index.js dans l'éditeur de code Cloud Shell.

Récupérer des messages

Une notification push Gmail inclut l'adresse e-mail à laquelle elle est associée et un ID d'historique. Pour plus de simplicité, dans cet atelier de programmation, vous demanderez simplement à l'API Gmail le dernier message lorsqu'une notification push arrive. Pour un meilleur résultat, utilisez plutôt l'ID d'historique pour rechercher les messages.

// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
  userId: email,
  maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;

// Get the message using the message ID.
const message = await gmail.users.messages.get({
  userId: email,
  id: messageId
});

return message;

Analyser les images jointes

Si le message comporte une image en pièce jointe, watchGmailMessages appelle l'API Cloud Vision pour annoter l'image. Dans cet atelier de programmation, vous allez demander à l'API Cloud Vision de classer l'image et de renvoyer un certain nombre de tags d'image. Par exemple, si vous lui fournissez une image d'un ciel bleu, l'API Cloud Vision peut renvoyer les tags bleu, ciel et nature.

watchGmailMessages utilise la bibliothèque de l'API Cloud Vision pour Node.js afin d'appeler l'API Cloud Vision :

// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
  var topLabels = ['', '', ''];
  if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
    const [analysis] = await visionClient.labelDetection({
      image: {
        content: Buffer.from(data, 'base64')
      }
    });
    const labels = analysis.labelAnnotations;
    topLabels = labels.map(x => x.description).slice(0, 3);
  }

  return topLabels;
};

Mettre à jour une feuille de calcul Google Sheets

watchGmailMessages : exporte les résultats de cette analyse dans une feuille de calcul Google Sheets. Il inclut le nom de l'expéditeur, le nom de la pièce jointe et les tags des pièces jointes d'images (le cas échéant).

Commencez par créer une feuille de calcul Google Sheets. Ouvrez Google Sheets, puis cliquez sur le modèle Vide sous Créer une feuille de calcul. Copiez l'ID de votre feuille. Par exemple, si l'adresse dans votre navigateur se présente comme suit :

https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0

L'ID de votre feuille de calcul est abcdefghij01234567890. Dans l'éditeur de code Cloud Shell, mettez à jour gcf-gmail-codelab/pubsub/env_vars.yaml et remplacez YOUR-GOOGLE-SHEET-ID par votre propre valeur.

watchGmailMessages se connecte à l'API Google Sheets pour ajouter des informations :

const updateReferenceSheet = async (from, filename, topLabels) => {
  await googleSheets.spreadsheets.values.append({
    spreadsheetId: SHEET,
    range: SHEET_RANGE,
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      range: SHEET_RANGE,
      majorDimension: 'ROWS',
      values: [
        [from, filename].concat(topLabels)
      ]
    }
  });
};

Dernière étape

Dans l'éditeur de code Cloud Shell, ouvrez gcf-gmail-codelab/pubsub/env_vars.yaml et remplacez YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET et YOUR-GOOGLE-CALLBACK-URL par vos propres valeurs. Vous trouverez ces valeurs dans la console Google Cloud : ouvrez Cloud Functions dans le menu de navigation de gauche, sélectionnez auth_init dans la liste des fonctions Cloud, puis recherchez la section Variables d'environnement.

Déployer le code

Exécutez la commande ci-dessous pour déployer la fonction Cloud Functions :

cd ~

cd gcf-gmail-codelab/pubsub

gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml

Si vous avez donné à votre sujet Cloud Pub/Sub un nom autre que gmail-watch, remplacez gmail-watch dans la commande ci-dessus par le nom de votre sujet. Le déploiement de la fonction Cloud peut prendre quelques secondes.

7. Essayer

Félicitations, vous avez terminé ! Envoyez-vous un e-mail avec une image en pièce jointe. Dans quelques secondes, la feuille de calcul Google Sheets que vous avez créée sera automatiquement mise à jour avec les informations que vous fournissez.