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 automatisée, et vous pouvez les utiliser pour automatiser facilement votre workflow quotidien. Dans cet atelier, vous allez créer une puissante extension Gmail qui classe automatiquement les e-mails dans des catégories et enregistre ces catégories dans une feuille de calcul Google Sheets. 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 connectées aux API G Suite et à d'autres services Google Cloud Platform. Ces fonctions:
- Autorisez l'accès sécurisé à vos données Gmail et Google Sheets
- Extraire les images jointes à tous les messages entrants
- Classer ces images à l'aide de l'API Cloud Vision
- Consignez 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 automatisée à 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.
- Vous disposez de connaissances de base sur JavaScript/Node.js.
2. Avant toute chose
Activer les API
Dans cet atelier, vous allez utiliser les produits/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 Functions as a Service sans serveur de Google qui vous permet d'exécuter des extraits de code individuels (appelés "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 latérale de navigation de gauche:
Recherchez Cloud Functions dans le menu de navigation et 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 la diffusion de flux de données et la diffusion d'événements. Dans cet atelier, il sert de service de messagerie entre Gmail et Google Cloud Functions.
Pour activer Google Cloud Pub/Sub, ouvrez la barre latérale de navigation de gauche, recherchez Pub/Sub et 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, dans la barre de navigation de gauche, recherchez Datastore et cliquez dessus. Sur la nouvelle page, cliquez sur Sélectionner le mode Datastore.
Pour cet atelier, vous pouvez utiliser n'importe quel emplacement de base de données. Cliquez sur Créer une base de données pour activer Google Cloud Datastore. cela peut prendre quelques minutes.
Google Cloud Vision
L'API Google Cloud Vision est un service de machine learning performant qui utilise des modèles pré-entraînés pour dégager des insights 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 de nouveau la barre latérale de navigation de gauche et recherchez API et Services. Cliquez sur Bibliothèque. Dans la section Rechercher des API et Services, saisissez Gmail. Dans les résultats de recherche, sélectionnez API Gmail, puis cliquez sur Activer.
Revenez à la page "Bibliothèque d'API". Recherchez l'API Google Sheets et activez-la.
Répétez la procédure. 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 via une ligne de commande à vos ressources Google Cloud Platform, directement depuis votre navigateur. Vous pouvez ainsi 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:
Un nouveau panneau s'affiche en bas de l'écran:
Cliquez sur le bouton Lancer l'éditeur de code pour lancer 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, doit 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 transmet la notification du nouveau message à Google Cloud Functions.
- À l'arrivée de la notification de nouveau message, une instance Cloud Functions se connecte à Gmail et récupère le nouveau message.
- Si l'e-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 une feuille de calcul Google Sheets de votre choix, en spécifiant qui envoie 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 l'autoriser à accéder à Gmail. Vous devez 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 l'écran de consentement OAuth.
Saisissez un nom dans le champ Nom de l'application (GCF + Gmail Codelab, par exemple). Ne modifiez pas les autres paramètres, faites défiler la page vers le bas, puis cliquez sur Enregistrer.
Créer un ID client associé
Passez à l'onglet Credentials (Identifiants). Cliquez sur Créer des identifiants, puis sélectionnez ID client OAuth. Sélectionnez le type d'application Web, attribuez-lui un nom (vous pouvez réutiliser l'atelier de programmation GCF + Gmail ici), 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, auth_init et auth_callback, qui fonctionnent ensemble pour effectuer le processus d'autorisation à l'aide de l'ID client et du code secret du 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 un accès limité à vos données à toute personne en possession.
auth_callbackles enregistre dans Cloud Datastore. - Les jetons d'actualisation sont utilisés pour 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. Ne modifiez pas les valeurs de YOUR-GOOGLE-CLIENT-CALLBACK-URL et YOUR-PUBSUB-TOPIC pour le moment.
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 des commandes bêta.
Accédez ensuite à la console Google Cloud, puis cliquez sur Cloud Functions dans le menu de navigation de gauche. Cliquez sur auth_callback dans la liste des fonctions Cloud Functions, puis accédez à l'onglet Déclencheur.
Copiez l'URL de la page. Revenez à la page Cloud Functions et 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., et 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 la procédure 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 le domaine suivant 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 se présente comme suit :
https://us-central1-my-project.cloudfunctions.net/auth_callback
Vous devez ajouter ce qui suit en tant qu'origine:
https://us-central1-my-project.cloudfunctions.net/
Appuyez sur Entrée pour confirmer, puis sur Enregistrer pour appliquer les modifications.
5. Configurer les notifications push Gmail
Si le processus d'autorisation aboutit, auth_callback appelle automatiquement l'API Gmail pour configurer les notifications push.
Pour recevoir des notifications push Gmail, vous devez créer un sujet Pub/Sub. Tous les abonnés au sujet reçoivent automatiquement des notifications de messages entrants dès leur arrivée depuis 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 sujet, par exemple gmail-watch, puis cliquez sur Créer. De plus, vous devez 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 et 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 et 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 et 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 que vous possédez. Dès qu'un nouveau message arrive dans la boîte de réception du compte, une notification push est déclenchée. Une fois que vous êtes connecté, la page ci-dessous s'affiche:
Cliquez sur Allow (Autoriser) pour autoriser l'accès. auth_callback terminera le processus d'autorisation, enregistrera les jetons d'accès et configurera les notifications push Gmail pour vous. Le message Successfully set up Gmail push notifications doit s'afficher dans votre navigateur une fois ce processus terminé.
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 indiqué précédemment, tout abonné au sujet Pub/Sub que vous avez créé recevra une notification 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, classera les images jointes et exportera ces catégories vers une feuille de calcul Google Sheets.
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 la notification est associée et un ID d'historique. Pour des raisons de simplicité, dans cet atelier de programmation, vous demanderez simplement à l'API Gmail le dernier message reçu lorsqu'une notification push arrive. Pour obtenir de meilleurs résultats, recherchez plutôt des messages à l'aide de l'ID de l'historique.
// 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 demanderez à l'API Cloud Vision de classer l'image et de renvoyer un certain nombre de tags. Par exemple, si l'API Cloud Vision est fournie avec une image d'un ciel bleu, elle peut renvoyer les tags blue, sky 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 la feuille de calcul Google Sheets
watchGmailMessages exporte les résultats de cette analyse dans une feuille de calcul Google Sheets. Elle comprend le nom de l'expéditeur et le nom de la pièce jointe, ainsi que les tags des images en pièces jointes (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 et recherchez la section Variables d'environnement.
Déployer le code
Exécutez la commande ci-dessous pour déployer la fonction Cloud:
cd ~ cd gcf-gmail-codelab/pubsub gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml
Si votre sujet Cloud Pub/Sub n'a pas nommé 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 contenant une image en pièce jointe. Après quelques secondes, la feuille de calcul Google Sheets que vous avez créée est automatiquement mise à jour avec les informations que vous avez fournies.