+180 XP

Gemini · Automatiser avec Apps Script et Workspace

Google Apps Script associé à l'API Gemini peut faire de Workspace non plus un endroit où vous travaillez, mais un endroit qui travaille pour vous. Un script peut étiqueter automatiquement les emails entrants selon leur intention, rédiger des brouillons de réponse ou compiler un rapport hebdomadaire dans Sheets à partir de lignes brutes, sans que vous y touchiez. Apps Script vit déjà dans Gmail, Sheets, Drive et Calendar avec un accès authentifié à vos données, et Gemini lui apporte le jugement. Vous reliez les deux avec un seul appel HTTP.

Cette leçon couvre le câblage, un exemple concret qui fonctionne et les garde-fous qui comptent dès que le script tourne sans surveillance sur un déclencheur.

Pourquoi Apps Script est la bonne colle

Apps Script est le runtime JavaScript serverless de Google intégré à Workspace. Vous n'avez rien à provisionner. Un script peut lire vos fils Gmail (GmailApp) et écrire dans une feuille de calcul (SpreadsheetApp). Il peut aussi s'exécuter sur un déclencheur temporel, le tout avec les autorisations de votre compte.

Ce qu'il n'a pas nativement, c'est le raisonnement. C'est le rôle de Gemini. Vous appelez l'API Gemini depuis le script avec `UrlFetchApp`, vous lui envoyez du texte et vous récupérez une sortie structurée.

Il existe deux façons d'authentifier l'appel :

  • Une clé API issue de Google AI Studio est le moyen le plus rapide de démarrer. Elle convient bien aux automatisations personnelles et aux prototypes.
  • Vertex AI avec un compte de service est le bon choix quand l'automatisation appartient à une organisation ou nécessite des contrôles IAM, de la résidence des données ou des périmètres VPC. Voir cloud.google.com/vertex-ai.

Pour un rapport hebdomadaire personnel, la clé API suffit. L'exemple ci-dessous l'utilise et signale où vous basculeriez.

L'exemple : un rapport hebdomadaire sur les emails de support

L'objectif : chaque lundi à 7 h, parcourir les emails de la semaine précédente étiquetés `support`, faire classer chacun par Gemini selon sa catégorie et son urgence, puis ajouter une ligne de synthèse propre dans une Sheet de suivi.

L'exemple est fiable parce qu'il utilise une sortie structurée. Vous demandez à Gemini de renvoyer du JSON conforme à un schéma plutôt que de la prose. L'API Gemini prend en charge un responseSchema, qui contraint le modèle à produire du JSON valide. Cela supprime l'étape fragile qui consiste à parser le paragraphe du modèle.

L'appel de classification

Voici le cœur du dispositif : une fonction qui envoie un lot d'objets et d'extraits d'emails et récupère des classifications typées.

javascript
const GEMINI_KEY = PropertiesService.getScriptProperties().getProperty('GEMINI_KEY');
const MODEL = 'gemini-flash-latest';

function classifyEmails(emails) {
  const url = `https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent?key=${GEMINI_KEY}`;
  const prompt = 'Classify each support email. Categories: billing, bug, feature_request, other. ' +
    'Urgency: low, medium, high.\n\n' +
    emails.map((e, i) => `[${i}] Subject: ${e.subject}\nSnippet: ${e.snippet}`).join('\n\n');

  const payload = {
    contents: [{ parts: [{ text: prompt }] }],
    generationConfig: {
      responseMimeType: 'application/json',
      responseSchema: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            index: { type: 'integer' },
            category: { type: 'string', enum: ['billing', 'bug', 'feature_request', 'other'] },
            urgency: { type: 'string', enum: ['low', 'medium', 'high'] }
          },
          required: ['index', 'category', 'urgency']
        }
      }
    }
  };

  const res = UrlFetchApp.fetch(url, {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify(payload),
    muteHttpExceptions: true
  });

  if (res.getResponseCode() !== 200) {
    throw new Error(`Gemini API ${res.getResponseCode()}: ${res.getContentText()}`);
  }
  const body = JSON.parse(res.getContentText());
  return JSON.parse(body.candidates[0].content.parts[0].text);
}

Les points auxquels un ingénieur senior serait attentif :

  • La clé est stockée dans les Script Properties, jamais dans le code source. Définissez-la une fois dans les paramètres du projet, ou exécutez PropertiesService.getScriptProperties().setProperty('GEMINI_KEY', '...').
  • gemini-flash-latest est un alias qui pointe vers le modèle Flash actuel. Flash est rapide et peu coûteux, et la classification est précisément ce qu'il fait bien. Réservez Pro aux synthèses longues ou aux jugements difficiles en plusieurs étapes.
  • L'alias protège un script sans surveillance contre le retrait des modèles. Google arrête les anciennes versions selon un calendrier publié, et un script figé sur un nom retiré échoue en silence chaque lundi. La contrepartie : le comportement peut changer quand l'alias évolue. Si vous avez besoin d'une sortie reproductible, figez une version précise depuis la page des modèles et consultez la liste des dépréciations tous les quelques mois.
  • muteHttpExceptions: true vous permet de lire le corps de l'erreur au lieu d'obtenir une exception générique. Vous voudrez ce texte dans vos logs.
  • Regroupez les emails en un seul appel. Envoyer une requête par email consomme du quota et du temps. Un seul prompt avec tous les extraits de la semaine précédente coûte bien moins cher, et le schéma garde les résultats alignés grâce à index.

Le branchement sur Gmail et Sheets

L'orchestration autour de l'appel relève de l'Apps Script classique :

javascript
function weeklyReport() {
  const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
  const query = `label:support after:${Utilities.formatDate(since, 'GMT', 'yyyy/MM/dd')}`;
  const threads = GmailApp.search(query, 0, 50);

  const emails = threads.map(t => {
    const msg = t.getMessages()[0];
    return { subject: msg.getSubject(), snippet: msg.getPlainBody().slice(0, 400) };
  });
  if (emails.length === 0) return;

  const results = classifyEmails(emails);

  const sheet = SpreadsheetApp.openById('YOUR_SHEET_ID').getSheetByName('Weekly');
  const counts = { billing: 0, bug: 0, feature_request: 0, other: 0, high: 0 };
  results.forEach(r => {
    counts[r.category]++;
    if (r.urgency === 'high') counts.high++;
  });
  sheet.appendRow([new Date(), emails.length, counts.billing, counts.bug,
    counts.feature_request, counts.other, counts.high]);
}

Configurez ensuite un déclencheur pour qu'il s'exécute sans surveillance. Dans l'éditeur, cliquez sur l'icône d'horloge (Déclencheurs), ou créez le déclencheur une fois dans le code :

javascript
function installTrigger() {
  ScriptApp.newTrigger('weeklyReport')
    .timeBased().onWeekDay(ScriptApp.WeekDay.MONDAY).atHour(7).create();
}

Exécutez installTrigger une fois. À partir de là, `weeklyReport` se lance chaque lundi matin sans aucune intervention humaine. C'est tout l'intérêt, et c'est aussi précisément là que le risque commence.

Garde-fous pour les exécutions sans surveillance

Un script qui tourne pendant votre sommeil, dispose de votre scope Gmail et appelle un modèle externe exige de la discipline. Les modes de défaillance diffèrent de ceux du prompting interactif, car personne ne regarde la sortie.

1. Limiter le rayon d'impact

Cet exemple se contente de lire Gmail et d'ajouter des lignes à une Sheet. Il ne supprime, n'envoie et ne modifie jamais de fils. Gardez par défaut des automatisations en lecture et ajout. Dès qu'un script peut envoyer des emails ou supprimer des fichiers sans surveillance, une mauvaise sortie du modèle ou un bug devient une action irréversible.

Si vous passez aux réponses automatiques ou à un étiquetage automatique qui déplace le courrier, ajoutez un mode dry-run : écrivez les actions proposées dans une Sheet pendant une semaine et relisez-les avant de laisser le script agir pour de vrai.

2. Ne demander que les scopes nécessaires

Apps Script déduit les scopes OAuth des API que vous appelez. Figez-les explicitement dans le manifeste pour qu'une nouvelle fonction égarée ne puisse pas élargir les accès en silence. Dans appsscript.json :

json
{
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

Avec gmail.readonly, même une version boguée ne peut ni envoyer ni supprimer de courrier. Cette seule ligne est votre garde-fou le plus solide.

3. Ne jamais confier le flux de contrôle à la sortie du modèle

Le modèle renvoie des catégories. Avant de les utiliser comme clés d'objet, validez-les par rapport aux valeurs autorisées par votre enum. Si une valeur inattendue arrive, consignez-la dans les logs et ignorez l'élément. Ne faites pas planter toute l'exécution et n'écrivez pas de données incohérentes dans la Sheet. La sortie structurée rend ce cas rare, et la vérification supplémentaire ne coûte presque rien.

4. Gérer le quota, la latence et les échecs partiels

Les appels UrlFetchApp échouent parfois, et Apps Script limite le temps d'exécution par lancement. Encapsulez l'appel API dans une logique de nouvelle tentative avec backoff pour les erreurs transitoires. Concevez le job pour qu'un échec le lundi ne fasse pas disparaître en silence les données du lundi :

javascript
function fetchWithRetry(url, options, tries = 3) {
  for (let i = 0; i < tries; i++) {
    const res = UrlFetchApp.fetch(url, options);
    if (res.getResponseCode() < 500) return res;
    Utilities.sleep(1000 * Math.pow(2, i));
  }
  throw new Error('Gemini API failed after retries');
}

5. Surveiller le coût et la confidentialité

Flash est peu coûteux, mais les coûts s'accumulent avec une boucle qui s'emballe ou un déclencheur mal configuré qui tourne toutes les heures. Définissez une alerte de facturation sur le projet.

Vous envoyez aussi le contenu d'emails à une API. Pour un usage personnel, la clé AI Studio est acceptable. Pour tout ce qui touche des données clients ou collaborateurs, passez à Vertex AI, qui vous apporte une gestion des données de niveau entreprise, l'IAM et la possibilité de conserver les données dans une région donnée. Pour les déploiements en organisation, c'est une exigence. C'est la frontière entre un prototype et un outil que la conformité validera.

Vérification des acquis

1. Selon la leçon, qu'apporte fondamentalement la combinaison d'Apps Script et de l'API Gemini que ni l'un ni l'autre ne possède pleinement seul ?

2. Pourquoi la leçon recommande-t-elle d'utiliser une sortie structurée (un responseSchema) lors de l'appel à Gemini depuis le script ?

3. Dans quel cas préféreriez-vous Vertex AI avec un compte de service à une clé API Google AI Studio ?

CHOIX MULTIPLES

4. Sélectionnez TOUTES les affirmations qui expliquent correctement pourquoi Apps Script est qualifié de « bonne colle » pour ce type d'automatisation.

Sélectionnez toutes les réponses correctes.

CHOIX MULTIPLES

5. Sélectionnez TOUTES les tâches que la leçon présente comme réalisables par cette automatisation Apps Script + Gemini.

Sélectionnez toutes les réponses correctes.

Quand dépasser Apps Script

Apps Script convient aux tâches qui vivent dans Workspace et accomplissent une seule tâche bornée selon un calendrier. Ce n'est plus le bon outil dès que vous avez besoin d'un véritable comportement d'agent en plusieurs étapes : des outils qui en appellent d'autres, de la planification, une mémoire entre les étapes ou une orchestration que vous voulez tester et versionner comme un vrai logiciel.

À ce stade, l'écosystème Gemini propose des options mieux adaptées :

  • Agent Development Kit (ADK) est un framework open source pour construire des agents avec des outils, de la planification et une orchestration multi-agents. Vous pouvez le déployer sur votre propre infrastructure ou sur Vertex AI Agent Engine. Utilisez-le quand la logique dépasse ce qu'un seul script peut porter.
  • Gemini CLI et Gemini Code Assist prennent en charge l'automatisation côté développeur, dans votre terminal et votre IDE. Ils ne sont pas conçus pour les workflows documentaires de Workspace.
  • Les Gems sont des assistants réutilisables, paramétrés par instructions, dans l'application Gemini. Utilisez-les quand un humain est dans la boucle et que vous n'avez pas besoin de code du tout.

La règle de décision est simple. Si la tâche consiste à « lire des données Workspace, poser une question ciblée à Gemini, réécrire le résultat dans Workspace, selon un calendrier », Apps Script l'emporte par sa simplicité. Si un agent doit décider quelles actions mener sur de nombreuses étapes, passez à ADK sur Vertex AI.

Un pattern à reprendre : enrichir le rapport

Vous pouvez rendre la synthèse hebdomadaire plus intelligente en demandant à Gemini de rédiger un court récit des tendances à côté des chiffres. Ajoutez un second appel qui prend les chiffres de la semaine et la ligne de la semaine précédente, et demande une note de deux phrases sur « ce qui a changé » à ajouter à la Sheet. Gardez ce prompt étroitement cadré et toujours contraint par un schéma (un seul champ texte `summary`) pour qu'il reste prévisible dans une exécution sans surveillance. C'est peu de raisonnement pour un gros gain de lisibilité, et cela reste bon marché sur Flash.

Points clés

  • Apps Script est la colle, Gemini est le jugement. Lisez les données Workspace avec les services natifs, appelez l'API Gemini avec UrlFetchApp et réécrivez les résultats, le tout sous votre propre authentification et avec un déclencheur temporel.
  • Utilisez la sortie structurée (responseSchema) et regroupez vos requêtes. Le JSON contraint supprime le parsing fragile, et un seul appel groupé par exécution l'emporte sur un appel par élément en coût, en vitesse et en quota.
  • Faites de la lecture et de l'ajout le comportement par défaut et figez des scopes OAuth minimaux. gmail.readonly dans appsscript.json offre une garantie de sécurité plus forte que n'importe quel commentaire de code. Ajoutez une revue en dry-run avant qu'un script n'envoie, ne déplace ou ne supprime quoi que ce soit.
  • Concevez pour l'échec sans surveillance. Utilisez des nouvelles tentatives avec backoff, une validation par rapport à vos enums, des alertes de facturation et des erreurs consignées que vous pouvez réellement lire. Utilisez un alias de modèle comme gemini-flash-latest, ou suivez les dates de dépréciation, pour qu'un nom de modèle retiré ne casse pas votre déclencheur.
  • Montez en gamme de façon délibérée. Restez sur Apps Script pour les tâches planifiées et bornées, et passez à ADK sur Vertex AI quand vous avez besoin d'une vraie orchestration d'agents ou de contrôles de données de niveau entreprise.

Questions fréquentes

Comment connecter Google Apps Script à l'API Gemini ?

Vous appelez l'API Gemini depuis Apps Script avec une seule requête HTTP via `UrlFetchApp`, en ciblant l'endpoint generateContent et en transmettant votre clé. Apps Script dispose déjà d'un accès authentifié à Gmail, Sheets, Drive et Calendar : il fournit les données, Gemini fournit le jugement. Stockez la clé dans les Script Properties plutôt que dans le fichier source.

Faut-il utiliser une clé API AI Studio ou Vertex AI pour une automatisation Workspace ?

Une clé API Google AI Studio convient pour des automatisations personnelles et des prototypes, et c'est le moyen le plus rapide de démarrer. Passez à Vertex AI avec un compte de service dès que l'automatisation appartient à une organisation ou touche des données clients ou salariés : vous disposez alors des contrôles IAM, d'une gestion des données de niveau entreprise et de la résidence des données. Ce changement marque en général la frontière entre un prototype et un outil que la conformité validera.

Comment obtenir de Gemini un JSON fiable plutôt qu'un paragraphe ?

Utilisez la sortie structurée : définissez `responseMimeType` sur `application/json` et passez un `responseSchema` dans `generationConfig`, ce qui contraint le modèle à produire un JSON valide conforme à votre schéma. Vous supprimez ainsi l'étape fragile du parsing de texte libre. Utilisez des valeurs `enum` pour des champs comme la catégorie ou l'urgence afin que la sortie reste dans un ensemble fixe.

Comment programmer un Apps Script pour qu'il s'exécute automatiquement chaque semaine ?

Ajoutez un déclencheur temporel, soit avec l'icône d'horloge dans l'éditeur Apps Script, soit en code avec `ScriptApp.newTrigger('weeklyReport').timeBased().onWeekDay(ScriptApp.WeekDay.MONDAY).atHour(7).create()`. Vous exécutez la fonction d'installation une seule fois, puis le job se lance seul, sans intervention humaine. Vérifiez que vous n'installez pas le déclencheur deux fois : un doublon signifie des exécutions en double et un coût API en double.

De quels garde-fous a besoin un Apps Script utilisant Gemini qui tourne sans supervision ?

Cinq choses : limiter le script à la lecture et à l'ajout pour qu'il ne puisse ni supprimer ni envoyer, fixer des scopes OAuth minimaux dans `appsscript.json` (`gmail.readonly` est le garde-fou le plus efficace à lui seul), valider la sortie du modèle contre votre propre enum avant de l'utiliser dans la logique de contrôle, relancer les appels `UrlFetchApp` en échec avec un backoff exponentiel, et configurer une alerte de facturation. Personne ne surveille la sortie quand le déclencheur se lance à 7 h, les échecs doivent donc être gérés dans le code. Avant de laisser un script envoyer ou déplacer quoi que ce soit, faites-le tourner une semaine en mode dry-run et écrivez les actions proposées dans un Sheet pour les relire.

Quand faut-il passer d'Apps Script à l'Agent Development Kit ?

Restez sur Apps Script quand la tâche est bornée : lire des données Workspace, poser une question ciblée à Gemini, réécrire le résultat, selon un planning. Passez à ADK sur Vertex AI quand vous avez besoin d'un vrai comportement d'agent : des outils qui appellent d'autres outils, de la planification, une mémoire entre les étapes, ou une orchestration que vous voulez versionner et tester comme du logiciel. ADK est un framework open source que vous pouvez déployer sur votre propre infrastructure ou sur Vertex AI Agent Engine.