Google Apps Script et l’API Gemini : extraction intelligente de données

La saisie manuelle est l’ennemie de la productivité. Si vos équipes extraient des données d’e-mails opérationnels (factures, confirmations de réservation, formulaires de retours clients), vous connaissez sans doute le casse-tête des méthodes de parsing traditionnelles. 

Historiquement, les développeurs s’appuyaient sur les expressions régulières (Regex) pour extraire des informations comme les numéros de facture ou les montants. Mais Regex est terriblement fragile : au moindre changement de modèle d’e-mail chez un fournisseur, ou à la moindre césure inattendue, tout l’extracteur se met à échouer en silence.

Dans ce tutoriel, je vous montre comment créer un pipeline entièrement automatisé et sans interface, qui règle ce problème grâce à l’IA générative. Nous allons écrire un script léger qui lit les messages Gmail non lus, envoie le texte non structuré à l’API Gemini pour une extraction intelligente, puis consigne les données JSON parfaitement structurées directement dans une feuille Google.

Prérequis :

• Un compte Google
• Bases de JavaScript (Google Apps Script)
• Une clé API Gemini

Qu’est-ce que Google Apps Script ?

Google Apps Script est une plateforme de développement cloud, rapide, basée sur JavaScript, qui permet d’automatiser, de personnaliser et d’étendre les applications Google Workspace comme Google Docs, Sheets, Slides, etc. 

La plateforme s’exécutant directement sur les serveurs de Google, vous n’avez pas à installer de logiciel, configurer d’environnements locaux ni gérer d’infrastructure. 

Apps Script permet aux développeurs et profils low-code d’interagir de façon programmatique avec les outils Google Workspace comme Docs, Sheets, Slides, Drive, et plus encore. Vous pouvez créer et exécuter des automatisations via des menus personnalisés, des boutons, des planifications temporelles, ou encore utiliser le service pour développer et publier des modules complémentaires sur Google Workspace Marketplace.

Comment fonctionne Google Apps Script

Google Apps Script masque toute la complexité de la configuration backend et de l’authentification aux API, pour vous laisser vous concentrer sur la logique et les données. Il y parvient grâce à plusieurs atouts :

• Éditeur cloud natif : vous écrivez, déboguez et déployez votre code JavaScript directement dans un IDE web intégré à votre navigateur.
• Services intégrés : au lieu de composer avec OAuth et des appels API complexes, vous utilisez des objets globaux prêts à l’emploi (comme SpreadsheetApp, MailApp ou DriveApp) pour interagir nativement avec les services Google.
• Déclencheurs événementiels : les scripts peuvent être lancés manuellement via des boutons de menu personnalisés, ou planifiés pour s’exécuter automatiquement avec des déclencheurs temporels (ex. : tous les jours à minuit) et événementiels (ex. : lorsqu’un utilisateur soumet un formulaire Google).

Architecture Google Apps Script : pipeline de Gmail vers Sheets

Avant d’écrire le script, cartographions le flux de données dans ce pipeline. L’architecture repose sur quatre composants qui travaillent de concert :

• Gmail (source) : le processus commence par l’interrogation de votre boîte de réception via des opérateurs de recherche standards (comme is:unread label:invoices). Le script isole les bons fils de discussion et extrait le corps en texte brut ainsi que les pièces jointes PDF.
• Apps Script (calcul) : couche d’orchestration. Il parcourt les fils non lus, formate les pièces jointes en données base64 et gère la logique de gestion des erreurs et du traitement par lots.
• API Gemini (moteur de transformation) : Apps Script envoie une charge utile multimodale (texte de l’e-mail + PDF) au modèle Gemini 2.5 Flash. En passant un schéma JSON strict dans l’appel API, on force le modèle à extraire des valeurs précises (fournisseur, montant total, devise), plutôt que de générer du texte conversationnel.
• Google Sheets (destination) : une fois le JSON structuré renvoyé par Gemini, Apps Script l’analyse, l’agrège dans un tableau unique et insère les données en lot dans la prochaine ligne vide de votre feuille active via setValues().

Pourquoi utiliser Google Apps Script comme couche de calcul ?

Le principal avantage est l’élimination totale de la charge d’infrastructure. Aucun serveur à provisionner, pas de conteneurs Docker à configurer, ni de flux OAuth compliqués à mettre en place pour lire vos e-mails ou écrire dans une feuille de calcul. 

Parce qu’Apps Script s’intègre nativement à des services comme GmailApp et SpreadsheetApp, Google gère l’authentification en interne. Vous écrivez simplement le code et reliez les points d’intégration.

Étape 1 : préparer votre environnement Google Apps Script

Avant d’écrire la moindre ligne, préparons les dépendances externes : obtenir l’accès à l’API Gemini, créer la feuille de destination et configurer Gmail pour taguer correctement les factures entrantes.

Générer la clé API Gemini

Pour alimenter notre extraction intelligente, nous avons besoin d’un accès à l’API Gemini.

1. Rendez-vous sur Google AI Studio et connectez-vous avec votre compte Google.
2. Dans le menu de navigation de gauche, cliquez sur Get API key.
3. Cliquez sur le bouton Create API key. Vous pouvez choisir de créer cette clé dans un projet Google Cloud existant ou laisser AI Studio en créer un nouveau pour vous.
4. Copiez la chaîne générée. 

Bonnes pratiques de sécurité : ne perdez pas cette clé, mais surtout ne la codez jamais en dur en clair dans votre code. Gardez-la dans votre presse-papiers ou un bloc-notes sécurisé pour l’instant : nous l’enregistrerons de manière sécurisée dans notre environnement Apps Script à l’étape suivante.

Préparer la feuille Google et sécuriser la clé

Nous avons besoin d’un espace de stockage pour les données extraites. Cette feuille servira aussi de tremplin pour notre script d’automatisation.

1. Définir les en-têtes de la base Créez une feuille Google vierge. Sur la première ligne, créez les colonnes suivantes pour correspondre au schéma JSON que nous définirons dans le script :

• Date
• Vendor
• Invoice Number
• Total Amount
• Currency
• Items Summary
• Email Link

Figez la première ligne pour garder les en-têtes visibles au fur et à mesure que les données s’accumulent.

2. Accéder à Apps Script et stocker la clé API Maintenant que la feuille existe, ouvrons l’éditeur Apps Script directement depuis celle-ci. Le code sera automatiquement lié à cette feuille de calcul.

1. Dans votre feuille Google, cliquez sur Extensions > Apps Script dans le menu supérieur.
2. Une fois l’éditeur ouvert, regardez la barre latérale de gauche et cliquez sur l’icône d’engrenage pour ouvrir les paramètres du projet.

3. Faites défiler jusqu’en bas pour trouver la section Script Properties.
4. Cliquez sur Add script property.
5. Dans Property, saisissez exactement GEMINI_API_KEY.
6. Dans Value, collez la clé API copiée depuis AI Studio.
7. Cliquez sur Save script properties.

Le code que nous écrirons ensuite récupérera cette valeur de façon sécurisée à l’exécution, sans exposer vos identifiants.

Étape 2 : écrire le code Google Apps Script

Dans l’éditeur Apps Script, supprimez tout code par défaut. Nous allons construire notre moteur d’automatisation brique par brique.

1. Configuration et interface

Nous commençons par définir un objet de configuration global. Bonne pratique de code : regrouper toutes les variables en dur dans un seul bloc, pour n’avoir à modifier que cette section.

Nous ajoutons aussi une fonction onOpen(). Ce déclencheur intégré d’Apps Script crée automatiquement un menu personnalisé dans votre feuille Google, permettant aux utilisateurs non techniques d’exécuter le script manuellement sans ouvrir l’éditeur.

const CONFIG = {
 searchQuery: "is:unread label:invoices",
 model: "gemini-2.5-flash",
 adminEmail: Session.getActiveUser().getEmail() // Automatically emails the script owner if it crashes
};

/**
* Creates a custom menu in Google Sheets so non-technical users can run the script manually.
*/
function onOpen() {
 const ui = SpreadsheetApp.getUi();
 ui.createMenu('🤖 AI Automations')
   .addItem('Fetch New Invoices', 'processInvoices')
   .addToUi();
}

2. L’orchestration

La fonction processInvoices() agit comme orchestrateur principal. Elle commence par récupérer en toute sécurité votre clé API depuis les Script Properties configurées précédemment. 

Ensuite, elle utilise le service intégré GmailApp pour interroger votre boîte.

En appelant GmailApp.search(CONFIG.searchQuery), le script récupère un tableau de fils d’e-mails correspondant à la règle is:unread label:invoices. 

S’il y a des correspondances, la fonction parcourt chaque fil, récupère le dernier message, extrait le corps en texte brut et isole les PDF joints.

function processInvoices() {
  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  if (!apiKey) {
    throw new Error("GEMINI_API_KEY is missing! Please set it in Script Properties.");
  }

  const threads = GmailApp.search(CONFIG.searchQuery);
  if (threads.length === 0) return;

  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const batchData = [];
  const processedThreads = [];

3. Traitement des e-mails et PDF multimodaux

En parcourant les fils, nous ciblons le dernier message. Or, les factures arrivent rarement en texte brut : elles sont quasi toujours en pièce jointe PDF. 

Grâce à Gemini 2.5 Flash, nativement multimodal, notre script parcourt latestMessage.getAttachments(), récupère les PDF, les convertit en chaîne Base64 et les transmet directement à l’API sous forme d’inlineData. 

Gemini « lit » visuellement le PDF et en extrait les données aussi facilement que du texte.

for (let i = 0; i < threads.length; i++) {
   const thread = threads[i];
   const latestMessage = thread.getMessages().pop();
  
   const emailBody = latestMessage.getPlainBody();
   const emailDate = latestMessage.getDate();
   const emailLink = https://mail.google.com/mail/u/0/#inbox/${thread.getId()};
   const attachments = latestMessage.getAttachments();
   try {
     const geminiParts = [];
     geminiParts.push({ text: "Extract invoice details from this email and any attached documents:\n\n" + emailBody });
    
     // Add PDF attachments as base64 to the prompt
     for (const attachment of attachments) {
       if (attachment.getContentType() === "application/pdf") {
         geminiParts.push({
           inlineData: {
             mimeType: "application/pdf",
             data: Utilities.base64Encode(attachment.getBytes())
           }
         });
       }
     }
     // Invoke Gemini API
     const extractedData = callGeminiAPI(apiKey, geminiParts);

4. Insertion en lot et gestion des erreurs

Pour optimiser les performances, nous n’écrivons pas ligne par ligne dans la feuille. 

Nous regroupons plutôt les objets JSON extraits dans un tableau (batchData) et écrivons le tout en une seule opération via setValues().

Remarquez le bloc try...catch. 

Si Gemini hallucine ou échoue sur un e-mail, le script ne plante pas. Il intercepte l’erreur et utilise MailApp.sendEmail() pour alerter immédiatement l’administrateur, garantissant une bonne observabilité.

 // Push to batch array instead of writing one-by-one
     batchData.push([
       emailDate,
       extractedData.vendor || "Unknown Vendor",
       extractedData.invoiceNumber || "N/A",
       extractedData.totalAmount || 0.00,
       extractedData.currency || "USD",
       extractedData.itemsSummary || "N/A",
       emailLink
     ]);
     processedThreads.push(thread);
   } catch (error) {
     MailApp.sendEmail(CONFIG.adminEmail, "🚨 Invoice Pipeline Error", error.toString());
   }
 }
 // Batch Write to Sheets
 if (batchData.length > 0) {
   const lastRow = Math.max(sheet.getLastRow(), 1);
   sheet.getRange(lastRow + 1, 1, batchData.length, batchData[0].length).setValues(batchData);
 }
 // Mark all processed threads as read so they aren't parsed again
 processedThreads.forEach(t => t.markRead());
}

Enfin, le script appelle thread.markRead() sur chaque e-mail traité. Ainsi, au prochain passage, il les ignorera et ne traitera que les nouveaux.

5. La fonction d’assistance pour l’API Gemini (mode JSON)

Lorsqu’ils appellent des LLM, les développeurs recourent souvent au prompt « Retourne un bloc JSON ». Or les modèles ajoutent fréquemment un habillage conversationnel (ex. : « Bien sûr, voici vos données : [JSON] »), ce qui fait planter les parseurs en aval.

En définissant responseMimeType: "application/json" et un responseSchema strict, nous forçons l’API REST Gemini à ne renvoyer qu’un objet JSON garanti, contenant exactement nos en-têtes de colonnes.

function callGeminiAPI(apiKey, partsArray) {
 const url = https://generativelanguage.googleapis.com/v1beta/models/${CONFIG.model}:generateContent?key=${apiKey};
  const responseSchema = {
   type: "OBJECT",
   properties: {
     vendor: { type: "STRING" },
     invoiceNumber: { type: "STRING" },
     totalAmount: { type: "NUMBER" },
     currency: { type: "STRING" },
     itemsSummary: { type: "STRING" }
   },
   required: ["vendor", "totalAmount"]
 };
  const payload = {
   contents: [{ parts: partsArray }],
   generationConfig: {
     responseMimeType: "application/json",
     responseSchema: responseSchema
   }
 };
  const options = {
   method: "POST",
   contentType: "application/json",
   payload: JSON.stringify(payload),
   muteHttpExceptions: true
 };
  const response = UrlFetchApp.fetch(url, options);
 const jsonResponse = JSON.parse(response.getContentText());
  return JSON.parse(jsonResponse.candidates[0].content.parts[0].text);
}

Étape 3 : automatiser votre pipeline Google Apps Script

Le code n’a de valeur que s’il vous simplifie la vie. 

Google Apps Script propose des modes d’exécution puissants, allant de boutons interactifs côté utilisateur à des tâches de fond totalement invisibles.

Méthode 1 : déclenchement via l’interface de la feuille

Si vous concevez cet outil pour une équipe comptable non technique, elle n’a sans doute pas envie d’ouvrir l’éditeur Apps Script pour traiter les factures du jour. 

Grâce à la fonction onOpen() dans notre code, Apps Script ajoute automatiquement un menu personnalisé dans l’interface de Google Sheets à chaque ouverture de la feuille.

1. Revenez sur votre feuille Google et actualisez la page.
2. Patientez quelques secondes, puis regardez la barre de menus. Un nouveau menu déroulant apparaît : 🤖 AI Automations.
3. Cliquez dessus et sélectionnez Fetch New Invoices.

4. Au premier lancement, Google vous demandera d’autoriser le script (lecture de Gmail et envoi d’e-mails en votre nom). Une fois l’autorisation donnée, le script s’exécute en temps réel. Vous verrez les lignes se remplir avec les données JSON extraites.

Méthode 2 : automatisation sans interface via des déclencheurs temporels

Si vous souhaitez une automatisation clé en main, utilisez les déclencheurs temporels natifs pour exécuter le pipeline en arrière-plan, de façon autonome.

1. Dans l’éditeur Apps Script, cliquez sur Triggers (icône d’horloge) dans la barre latérale gauche.

2. Cliquez sur Add Trigger en bas à droite.

3. Définissez la fonction sur processInvoices.
4. Changez la source d’événement en Time-driven et programmez une exécution horaire (par exemple, toutes les 6 heures).
5. Cliquez sur Save.

Votre pipeline IA sans interface est désormais totalement autonome.

Même si votre ordinateur est éteint, les serveurs de Google se réveillent toutes les six heures, analysent votre boîte de réception, extraient les factures via Gemini, enregistrent les données dans Sheets, puis se rendorment. 

Vous pouvez suivre la réussite ou l’échec de ces exécutions en arrière-plan dans l’onglet Executions de l’éditeur Apps Script.

Étape 4 : tester l’extraction IA

Maintenant que le code est en place, testons-le pour valider le bon fonctionnement du pipeline d’extraction.

Voyons deux cas concrets pour évaluer la gestion de différents formats et la forme réelle des réponses de l’API Gemini.

Test 1 : extraction depuis un e-mail en texte brut

Commençons par une facture intégrée directement dans le corps de l’e-mail.

1. Envoyez-vous un e-mail avec l’objet « Invoice INV-2023-88493 ».
2. Dans le corps, écrivez un texte non structuré du type : « Bonjour, merci de payer Acme Corp 450,00 $ USD pour la licence logicielle T3. »
3. Appliquez le libellé invoices à l’e-mail et laissez-le non lu.

4. Lancez le script via le menu personnalisé.

En coulisses, Gemini reçoit ce texte non structuré et respecte strictement notre schéma JSON. 

Au lieu d’une réponse verbeuse, il renvoie une charge utile brute. 

Comme la réponse est un JSON parfaitement structuré, notre tableau batchData.push() lit sans friction extractedData.totalAmount et consigne 6550 directement dans Google Sheets, sans la moindre Regex complexe.

Test 2 : extraction depuis une pièce jointe PDF

Testons maintenant la vraie puissance de Gemini 2.5 Flash en lui transmettant un document PDF.

1. Générez ou téléchargez un exemple de facture PDF (par ex. : 20 700,00 $ émise par ProTech Cloud Services).
2. Envoyez-vous le PDF en pièce jointe. Le corps de l’e-mail peut rester vide.
3. Appliquez le libellé invoices et marquez-le comme non lu.

4. Exécutez le script. Le pipeline détectera la pièce jointe, la convertira en Base64, et Gemini lira visuellement le document pour extraire le fournisseur et le montant total.

C’est ici que l’architecture révèle tout son intérêt. 

Vous n’avez pas eu à écrire de logique d’OCR (reconnaissance optique de caractères), à gérer une bibliothèque tierce de parsing PDF, ni à bricoler des expressions régulières pour trouver le montant total. 

Le LLM a géré nativement la donnée visuelle non structurée.

Conclusion

Automatiser des workflows métier ne nécessite pas de lourde infrastructure ni de boucles d’autorisation complexes. 

En associant Google Apps Script à l’API Gemini, nous avons construit un pipeline de données intelligent et serverless, qui fonctionne entièrement dans l’écosystème cloud que vous utilisez déjà au quotidien.

La force de cette architecture réside dans sa simplicité. Plutôt que de provisionner des serveurs, de configurer des webhooks ou de gérer des fichiers d’identifiants sur un serveur externe, Apps Script gère nativement le contexte, l’authentification et l’exécution. 

De son côté, Gemini évite d’avoir recours à des expressions régulières fragiles ou à des solutions d’OCR coûteuses, et transforme des corps d’e-mails brouillons et des PDF non structurés en lignes de base de données prévisibles avec un seul appel API.

Pour aller plus loin et explorer ce que vous pouvez construire avec un accès programmatique aux LLM, nous vous recommandons le cours de DataCamp Introduction to APIs in Python ou la conception de workflows intelligents avec le cours AI Agent Fundamentals .