Créer des étapes Google Workspace Studio personnalisées dans Node.js sur Cloud Run

1. Introduction

Google Workspace Studio vous permet d'automatiser les processus métier dans les applications Google Workspace telles que Gmail, Google Chat, Google Drive et Google Sheets. Lorsque vos workflows doivent démarrer à partir d'une application Web externe ou exécuter une logique personnalisée dans votre propre environnement cloud, vous pouvez étendre Google Workspace Studio avec un module complémentaire Google Workspace HTTP en Node.js sur Cloud Run :

1. Étape de déclencheur personnalisé (workflowTrigger) : démarre un flux Google Workspace Studio lorsqu'un événement externe se produit (par exemple, un client envoie un ticket dans un portail Web interne) en appelant le notifyUri du déclencheur (ou l'API REST triggers.fire de Google Workspace Studio).
2. Étape d'action personnalisée (workflowAction) : reçoit des variables des étapes précédentes du flux, exécute une logique personnalisée ou une inférence d'IA dans votre service Node.js et renvoie des variables de sortie à Google Workspace Studio.

Dans cet atelier de programmation, vous allez créer et déployer une extension HTTP Node.js complète pour Google Workspace Studio sur Cloud Run, utiliser Cloud Firestore pour conserver les abonnements actifs aux déclencheurs de flux et les tickets envoyés dans les différentes révisions de conteneur, utiliser Cloud Tasks pour réessayer automatiquement les notifications de déclencheur si notifyUri ne renvoie pas de réponse de réussite, et classer l'urgence des tickets dans votre étape d'action personnalisée à l'aide de Gemini 3.8 Flash (gemini-3.8-flash) sur Gemini Enterprise Agent Platform avec une solution de secours résiliente basée sur la correspondance de mots clés.

Conseil : Vous utilisez un agent de programmation IA ? Si vous utilisez Antigravity CLI (agy) ou Gemini CLI, vous pouvez également automatiser ce workflow à l'aide de la compétence d'agent workspace-studio-node-addon réutilisable sur GitHub.

Objectifs de l'atelier

• Une application Web Support Quick Portal et un module complémentaire Google Workspace HTTP créés avec Node.js, Express, Firestore et Cloud Tasks sur Cloud Run.
• Une étape de déclencheur personnalisé New Support Ticket (supportTicketTrigger) qui conserve les abonnements actifs aux flux dans une collection Firestore studio_triggers, enregistre les tickets envoyés dans une collection Firestore support_tickets et se déclenche chaque fois qu'un ticket est envoyé dans le portail Web, en transmettant ticketTitle et ticketDescription dans un flux Google Workspace Studio.
• Un worker de nouvelle tentative Cloud Tasks (file d'attente studio-trigger-retries et POST /api/tasks/fire-trigger) qui met en file d'attente et réessaye les appels de déclencheur ayant échoué avec un intervalle exponentiel entre les tentatives à l'aide du dernier userOAuthToken stocké dans Firestore, garantissant la diffusion vers notifyUri.
• Une étape d'action personnalisée Detect Urgency (urgencyDetectorStep) qui classe l'urgence des tickets à l'aide de Gemini 3.8 Flash (gemini-3.8-flash) sur Gemini Enterprise Agent Platform (aiplatform.googleapis.com), avec une solution de secours automatique basée sur la correspondance de mots clés (urgent, blocker, critical).

Architecture

Le schéma suivant illustre l'interaction entre Support Quick Portal, votre module complémentaire Node.js sur Cloud Run, Cloud Firestore, Cloud Tasks (studio-trigger-retries), Gemini 3.8 Flash et Google Workspace Studio, de l'enregistrement du flux à l'exécution de l'action en passant par la diffusion résiliente du déclencheur :

Points abordés

• Configurer un fichier manifeste de déploiement de module complémentaire Google Workspace HTTP (deployment.json) avec des éléments workflowTrigger et workflowAction.
• Conserver les abonnements aux déclencheurs Google Workspace Studio (triggerId, notifyUri et userOAuthToken) dans une collection Firestore studio_triggers et déclencher des flux à l'aide de notifyUri / triggers.fire.
• Utiliser Cloud Tasks (@google-cloud/tasks) pour réessayer les notifications de déclencheur ayant échoué avec un intervalle exponentiel entre les tentatives jusqu'à ce que notifyUri renvoie une réponse de réussite 2xx.
• Créer une étape personnalisée workflowAction en Node.js à l'aide de la sortie structurée Gemini 3.8 Flash (gemini-3.8-flash) sur Gemini Enterprise Agent Platform avec une solution de secours basée sur les mots clés.

Prérequis

• Un compte Google Workspace ayant accès à Google Workspace Studio.
• Un projet Google Cloud pour lequel la facturation est activée, créé dans la même organisation Google Workspace que votre compte utilisateur afin que vous puissiez installer des déploiements de modules complémentaires non publiés à des fins de test.

Attention : Cet atelier utilise des ressources Cloud payantes. Pour éviter des frais permanents, suivez les étapes de nettoyage à la fin de l'atelier.

2. Configurer votre projet Google Cloud, Firestore et Cloud Tasks

Dans cette étape, vous allez configurer l'écran de consentement OAuth de votre projet, activer les API Google Cloud et Google Workspace requises dans Cloud Shell, provisionner votre base de données Firestore (default), créer votre file d'attente de nouvelles tentatives Cloud Tasks et initialiser votre compte de service d'autorisation de module complémentaire.

1. Ouvrez la console Google Cloud, sélectionnez votre projet Google Cloud, puis cliquez sur l'icône Activer Cloud Shell dans la barre de navigation supérieure.
2. Configurez l'écran de consentement OAuth afin que Google Workspace puisse provisionner un client OAuth pour votre module complémentaire :
   1. Ouvrez la page Branding de Google Auth Platform.
   2. Si vous y êtes invité, cliquez sur Premiers pas. (Si votre écran de consentement est déjà configuré, passez à l'étape 3.)
   3. Sous Informations sur l'application, saisissez Support Extension pour le nom de l'application, sélectionnez votre adresse e-mail d'assistance utilisateur, puis cliquez sur Suivant.
   4. Sous Audience, sélectionnez Interne, puis cliquez sur Suivant.
   5. Sous Coordonnées, saisissez votre adresse e-mail, puis cliquez sur Suivant.
   6. Sous Terminer, acceptez le Règlement sur les données utilisateur dans les services d'API Google, cliquez sur Continuer, puis sur Créer.
3. Dans Cloud Shell, définissez votre projet actif (remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud) et activez les API requises :

   gcloud config set project YOUR_PROJECT_ID
   gcloud services enable \
     aiplatform.googleapis.com \
     firestore.googleapis.com \
     cloudtasks.googleapis.com \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     artifactregistry.googleapis.com \
     appsmarket-component.googleapis.com \
     gsuiteaddons.googleapis.com \
     workspacestudio.googleapis.com
   

4. Provisionnez votre base de données Firestore (default) et la file d'attente Cloud Tasks studio-trigger-retries dans us-central1 (si elles n'existent pas déjà), puis initialisez votre compte de service Google Workspace Add-ons :

   gcloud firestore databases describe --database="(default)" >/dev/null 2>&1 || \
     gcloud firestore databases create \
       --database="(default)" \
       --location=us-central1 \
       --type=firestore-native \
       --quiet
   
   gcloud tasks queues describe studio-trigger-retries --location=us-central1 >/dev/null 2>&1 || \
     gcloud tasks queues create studio-trigger-retries \
       --location=us-central1 \
       --max-attempts=5 \
       --min-backoff=10s \
       --max-backoff=300s \
       --max-doublings=4
   
   gcloud workspace-add-ons get-authorization
   

Pourquoi activer appsmarket-component.googleapis.com, Firestore et Cloud Tasks maintenant ? La configuration de l'écran de consentement OAuth et l'activation du SDK Google Workspace Marketplace (appsmarket-component.googleapis.com) ainsi que de l'API Google Workspace Add-ons (gsuiteaddons.googleapis.com) provisionnent automatiquement le client OAuth et le compte de service par défaut de votre projet. Le provisionnement de la base de données Firestore (default) et de la file d'attente de tâches Cloud Tasks studio-trigger-retries prépare le stockage persistant pour studio_triggers et support_tickets, et configure les nouvelles tentatives automatiques avec intervalle exponentiel entre les tentatives (--max-attempts=5 --min-backoff=10s --max-backoff=300s) chaque fois qu'une notification de déclencheur échoue.

3. Créer l'application Node.js avec Firestore, Cloud Tasks et Gemini 3.8 Flash

Dans cette étape, vous allez créer l'application Node.js dans ~/studio-support-addon. Pour que le code reste modulaire et lisible, vous allez organiser le projet en six fichiers ciblés :

• firestore.js : initialise le client Cloud Firestore (collections studio_triggers et support_tickets) et actualise les jetons OAuth mis en cache.
• starter.js : implémente les Webhooks de l'étape de déclencheur personnalisé New Support Ticket (/onConfigTrigger et /onManageTrigger).
• action.js : implémente les Webhooks de l'étape d'action personnalisée Detect Urgency (/onConfigUrgency et /onExecuteUrgency) à l'aide de Gemini 3.8 Flash (gemini-3.8-flash) avec une solution de secours basée sur la correspondance de mots clés.
• tasks.js : distribue les notifications de déclencheur à trigger.notifyUri (en revenant à https://workspacestudio.googleapis.com/v1/triggers/{triggerId}:fire), met en file d'attente les diffusions ayant échoué dans la file d'attente Cloud Tasks studio-trigger-retries et implémente le point de terminaison du worker de nouvelle tentative POST /api/tasks/fire-trigger.
• portal.js : diffuse l'interface utilisateur Web Support Quick Portal (GET /) et déclenche les déclencheurs Google Workspace Studio actifs (POST /api/submit-ticket), avec une option permettant de simuler un échec temporaire et de regarder Cloud Tasks réessayer.
• index.js : relie toutes les routes Express et démarre le serveur HTTP.

Initialiser le projet et package.json

1. Créez un répertoire de projet et accédez à celui-ci :

   mkdir -p ~/studio-support-addon && cd ~/studio-support-addon
   

2. Créez package.json avec express, @google-cloud/firestore, @google-cloud/tasks et @google/genai :

   cat << 'EOF' > package.json
   {
     "name": "studio-support-addon",
     "version": "1.0.0",
     "type": "module",
     "main": "index.js",
     "scripts": {
       "start": "node index.js"
     },
     "dependencies": {
       "@google-cloud/firestore": "^7.11.0",
       "@google-cloud/tasks": "^5.6.0",
       "@google/genai": "^1.0.0",
       "express": "^4.21.2"
     }
   }
   EOF
   

firestore.js : état Firestore partagé et actualisation du jeton OAuth

Créez firestore.js pour gérer vos deux collections Firestore et actualiser les jetons OAuth utilisateur mis en cache :

• studio_triggers : stocke les abonnements actifs aux flux Google Workspace Studio (triggerId, notifyUri et userOAuthToken) afin qu'ils survivent aux redémarrages des conteneurs Cloud Run et aux événements de scaling à zéro instance.
• support_tickets : stocke un enregistrement de chaque demande d'assistance envoyée via le portail.
• refreshTokenInFirestore(req) : chaque fois que Google Workspace Studio appelle l'un de vos points de terminaison de Webhook, il inclut un authorizationEventObject.userOAuthToken de courte durée. Cet assistant met à jour les documents de déclencheur actifs avec le dernier jeton afin que les appels triggers.fire en arrière-plan restent autorisés.

cat << 'EOF' > firestore.js
import { Firestore } from '@google-cloud/firestore';

export const db = new Firestore({
  projectId: process.env.GOOGLE_CLOUD_PROJECT || undefined,
  databaseId: '(default)',
  ignoreUndefinedProperties: true,
});

export const triggersCollection = db.collection(
  process.env.FIRESTORE_TRIGGERS_COLLECTION || 'studio_triggers'
);

export const ticketsCollection = db.collection(
  process.env.FIRESTORE_TICKETS_COLLECTION || 'support_tickets'
);

// Keep cached userOAuthToken fresh across active trigger documents
export async function refreshTokenInFirestore(req) {
  const freshToken = req.body?.authorizationEventObject?.userOAuthToken;
  if (!freshToken) return;
  try {
    const snapshot = await triggersCollection.get();
    if (snapshot.empty) return;
    const batch = db.batch();
    snapshot.docs.forEach((doc) => {
      batch.set(
        doc.ref,
        { userOAuthToken: freshToken, updatedAt: new Date().toISOString() },
        { merge: true }
      );
    });
    await batch.commit();
  } catch (err) {
    console.error('Error refreshing OAuth token in Firestore:', err.message);
  }
}
EOF

Pourquoi conserver les déclencheurs dans Firestore plutôt que dans des fichiers locaux ? Le stockage des abonnements actifs aux déclencheurs Google Workspace Studio dans la collection Firestore studio_triggers dissocie l'état de votre module complémentaire du stockage éphémère des conteneurs. Votre service Cloud Run peut effectuer un scaling à la baisse jusqu'à zéro lorsqu'il est inactif, effectuer un scaling horizontal sur plusieurs instances et déployer de nouvelles révisions de conteneur sans perdre les déclencheurs de flux enregistrés.

starter.js : étape de déclencheur personnalisé (workflowTrigger)

Créez starter.js pour implémenter les deux points de terminaison de Webhook requis par une étape de déclencheur personnalisé Google Workspace Studio :

• onConfigTrigger (POST /onConfigTrigger) : appelé lorsqu'un utilisateur sélectionne Nouvelle demande d'assistance comme déclencheur de son flux dans Google Workspace Studio. Renvoie une action de navigation pushCard décrivant le déclencheur.
• onManageTrigger (POST /onManageTrigger) : appelé lorsqu'un utilisateur active un flux (req.body.workflow.triggerCreation) ou le désactive / le supprime (req.body.workflow.triggerDeletion). Enregistre ou supprime le document d'abonnement dans la collection Firestore studio_triggers.

cat << 'EOF' > starter.js
import { triggersCollection, refreshTokenInFirestore } from './firestore.js';

// Custom Starter Configuration Card
export async function onConfigTrigger(req, res) {
  await refreshTokenInFirestore(req);
  res.status(200).json({
    action: {
      navigations: [
        {
          pushCard: {
            sections: [
              {
                header: 'Support Ticket Listener',
                widgets: [
                  {
                    textParagraph: {
                      text: 'This starter listens for new tickets submitted through the Support Quick Portal and stores subscriptions in Firestore.',
                    },
                  },
                ],
              },
            ],
          },
        },
      ],
    },
  });
}

// Custom Starter Subscription Lifecycle (Firestore studio_triggers collection)
export async function onManageTrigger(req, res) {
  try {
    const triggerCreation = req.body?.workflow?.triggerCreation;
    const triggerDeletion = req.body?.workflow?.triggerDeletion;
    const userOAuthToken =
      req.body?.authorizationEventObject?.userOAuthToken || null;

    if (triggerCreation?.triggerId) {
      const triggerId = String(triggerCreation.triggerId);
      const docId = encodeURIComponent(triggerId);
      await triggersCollection.doc(docId).set(
        {
          triggerId,
          notifyUri: triggerCreation.notifyUri || null,
          ...(userOAuthToken ? { userOAuthToken } : {}),
          updatedAt: new Date().toISOString(),
        },
        { merge: true }
      );
    }

    if (triggerDeletion?.triggerId) {
      const triggerId = String(triggerDeletion.triggerId);
      const docId = encodeURIComponent(triggerId);
      await triggersCollection.doc(docId).delete();
    }

    if (!triggerCreation && !triggerDeletion && userOAuthToken) {
      await refreshTokenInFirestore(req);
    }
  } catch (err) {
    console.error('Error in /onManageTrigger:', err.message);
  }
  res.status(200).json({});
}
EOF

action.js : étape d'action personnalisée (workflowAction) avec Gemini 3.8 Flash

Créez action.js pour implémenter les deux points de terminaison de Webhook requis par une étape d'action personnalisée Google Workspace Studio :

• onConfigUrgency (POST /onConfigUrgency) : renvoie une carte de configuration avec un widget textInput qui définit hostAppDataSource.workflowDataSource.includeVariables: true, ce qui permet aux utilisateurs de sélectionner la variable ticketDescription générée par l'étape de déclencheur.
• onExecuteUrgency (POST /onExecuteUrgency) : lit l'entrée ticketDescription à partir de req.body.workflow.actionInvocation.inputs, classe son impact commercial et son urgence à l'aide de Gemini 3.8 Flash (gemini-3.8-flash) sur Gemini Enterprise Agent Platform avec une sortie structurée (responseSchema enum ["High", "Normal"]), revient à detectKeywordUrgency() (urgent, blocker, critical) si l'appel de modèle échoue et renvoie la variable de sortie urgencyLevel à l'aide de hostAppAction.workflowAction.returnOutputVariablesAction.

cat << 'EOF' > action.js
import { GoogleGenAI, Type } from '@google/genai';
import { refreshTokenInFirestore } from './firestore.js';

// Initialize Google GenAI SDK for the Gemini Enterprise Agent Platform
const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: 'global',
});

// Fallback keyword classifier if the Gemini API call is unavailable
export function detectKeywordUrgency(description) {
  const lower = (description || '').toLowerCase();
  return lower.includes('urgent') ||
    lower.includes('blocker') ||
    lower.includes('critical')
    ? 'High'
    : 'Normal';
}

// Custom Action Step Configuration Card
export async function onConfigUrgency(req, res) {
  await refreshTokenInFirestore(req);
  res.status(200).json({
    action: {
      navigations: [
        {
          pushCard: {
            sections: [
              {
                header: 'Urgency Detector Step',
                widgets: [
                  {
                    textInput: {
                      name: 'ticketDescription',
                      label: 'Source Description',
                      hintText:
                        'Select the description variable outputted by the starter',
                      hostAppDataSource: {
                        workflowDataSource: {
                          includeVariables: true,
                        },
                      },
                    },
                  },
                ],
              },
            ],
          },
        },
      ],
    },
  });
}

// Custom Action Step Execution: Gemini 3.8 Flash with keyword fallback
export async function onExecuteUrgency(req, res) {
  await refreshTokenInFirestore(req);
  const inputs = req.body?.workflow?.actionInvocation?.inputs || {};
  const description = inputs.ticketDescription?.stringValues?.[0] || '';

  let urgencyLevel = detectKeywordUrgency(description);
  try {
    const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash',
      contents: `Evaluate the business impact and time sensitivity of this support ticket description and classify its urgency:\n\n${description}`,
      config: {
        responseMimeType: 'text/x.enum',
        responseSchema: {
          type: Type.STRING,
          enum: ['High', 'Normal'],
        },
      },
    });
    const candidate = (response.text || '').trim();
    if (candidate === 'High' || candidate === 'Normal') {
      urgencyLevel = candidate;
    }
  } catch (err) {
    console.error('Gemini fallback to keyword matching:', err.message);
  }

  res.status(200).json({
    hostAppAction: {
      workflowAction: {
        returnOutputVariablesAction: {
          variables: {
            urgencyLevel: {
              stringValues: [urgencyLevel],
            },
          },
        },
      },
    },
  });
}
EOF

tasks.js : file d'attente de nouvelles tentatives Cloud Tasks et point de terminaison du worker

Créez tasks.js pour distribuer les appels de déclencheur à trigger.notifyUri (en revenant à https://workspacestudio.googleapis.com/v1/triggers/{triggerId}:fire), mettre en file d'attente les appels ayant échoué dans votre file d'attente Cloud Tasks studio-trigger-retries et traiter les nouvelles tentatives sur POST /api/tasks/fire-trigger :

• resolveTriggerUrl(trigger) : utilise trigger.notifyUri conservé à partir de triggerCreation.notifyUri lorsqu'il est présent, ou revient à https://workspacestudio.googleapis.com/v1/triggers/{triggerId}:fire.
• fireTriggerDirect(trigger, payload) : envoie la requête POST à l'URL du déclencheur avec les variables de sortie ticketTitle et ticketDescription, ainsi qu'un requestId idempotent.
• enqueueTriggerRetry(req, payload) : met en file d'attente une tâche HTTP dans la file d'attente studio-trigger-retries ciblant le point de terminaison POST /api/tasks/fire-trigger de votre service Cloud Run chaque fois que l'appel de déclencheur initial échoue ou renvoie un état HTTP non 2xx.
• handleFireTriggerTask (POST /api/tasks/fire-trigger) : appelé par Cloud Tasks à chaque tentative. Recherche le dernier document trigger dans studio_triggers à partir de Firestore (en s'assurant que les nouvelles tentatives utilisent toujours le userOAuthToken le plus récent), vérifie l'en-tête X-CloudTasks-TaskRetryCount (si simulateFailure est activé, la première exécution de Cloud Tasks échoue avec 503 afin que vous puissiez voir Cloud Tasks réessayer après un intervalle entre les tentatives et réussir à la tentative #1), et renvoie 200 OK uniquement lorsque notifyUri renvoie une réponse de réussite 2xx. Toute réponse 5xx indique à Cloud Tasks de réessayer conformément à la règle d'intervalle entre les tentatives de votre file d'attente.

cat << 'EOF' > tasks.js
import { CloudTasksClient } from '@google-cloud/tasks';
import { triggersCollection } from './firestore.js';

const tasksClient = new CloudTasksClient();
const PROJECT_ID = process.env.GOOGLE_CLOUD_PROJECT;
const LOCATION = process.env.CLOUD_TASKS_LOCATION || 'us-central1';
const QUEUE = process.env.CLOUD_TASKS_QUEUE || 'studio-trigger-retries';

// Prefer trigger.notifyUri from triggerCreation, falling back to triggers.fire
export function resolveTriggerUrl(trigger) {
  return (
    trigger.notifyUri ||
    `https://workspacestudio.googleapis.com/v1/triggers/${encodeURIComponent(trigger.triggerId)}:fire`
  );
}

// Call the Google Workspace Studio trigger URL directly
export async function fireTriggerDirect(
  trigger,
  { title, description, requestId }
) {
  const targetUrl = resolveTriggerUrl(trigger);
  const response = await fetch(targetUrl, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${trigger.userOAuthToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'triggers/' + trigger.triggerId,
      outputs: {
        ticketTitle: { stringValues: [title] },
        ticketDescription: { stringValues: [description] },
      },
      requestId,
    }),
  });
  return { ok: response.ok, status: response.status, targetUrl };
}

// Enqueue a retry task in Cloud Tasks targeting POST /api/tasks/fire-trigger
export async function enqueueTriggerRetry(req, payload) {
  const parent = tasksClient.queuePath(PROJECT_ID, LOCATION, QUEUE);
  const baseUrl = process.env.SERVICE_URL || `https://${req.get('host')}`;
  const workerUrl = `${baseUrl}/api/tasks/fire-trigger`;

  const task = {
    httpRequest: {
      httpMethod: 'POST',
      url: workerUrl,
      headers: { 'Content-Type': 'application/json' },
      body: Buffer.from(JSON.stringify(payload)).toString('base64'),
    },
  };

  const [response] = await tasksClient.createTask({ parent, task });
  return response.name;
}

// Cloud Tasks worker endpoint: retries calling notifyUri using fresh Firestore state
export async function handleFireTriggerTask(req, res) {
  const { triggerId, title, description, requestId, simulateFailure } =
    req.body || {};
  const retryCount = Number(req.get('X-CloudTasks-TaskRetryCount') || 0);

  if (!triggerId) {
    return res.status(200).json({ skipped: true, reason: 'Missing triggerId' });
  }

  try {
    const docId = encodeURIComponent(String(triggerId));
    const doc = await triggersCollection.doc(docId).get();
    if (!doc.exists) {
      return res
        .status(200)
        .json({ skipped: true, reason: 'Trigger no longer active' });
    }

    const trigger = doc.data();
    if (!trigger.userOAuthToken) {
      return res
        .status(503)
        .json({ ok: false, error: 'Missing userOAuthToken in Firestore' });
    }

    // When simulateFailure is enabled, fail the 1st Cloud Task attempt (retryCount === 0)
    // so learners can observe Cloud Tasks back off and succeed on retry #1.
    if (simulateFailure && retryCount < 1) {
      console.warn(
        `[Cloud Tasks] Simulated transient failure on initial task attempt (retryCount=${retryCount}) for trigger ${triggerId}`
      );
      return res
        .status(503)
        .json({ ok: false, simulated: true, retryCount, triggerId });
    }

    const outcome = await fireTriggerDirect(trigger, {
      title,
      description,
      requestId,
    });

    if (outcome.ok) {
      console.log(
        `[Cloud Tasks] Successfully delivered trigger ${triggerId} to ${outcome.targetUrl} on retryCount=${retryCount}`
      );
      return res
        .status(200)
        .json({ ok: true, status: outcome.status, retryCount });
    }

    console.error(
      `[Cloud Tasks] Non-2xx response (${outcome.status}) from ${outcome.targetUrl} on retryCount=${retryCount}`
    );
    return res
      .status(502)
      .json({ ok: false, status: outcome.status, retryCount });
  } catch (err) {
    console.error(
      `[Cloud Tasks] Error firing trigger ${triggerId} on retryCount=${retryCount}:`,
      err.message
    );
    return res
      .status(503)
      .json({ ok: false, error: err.message, retryCount });
  }
}
EOF

Pourquoi acheminer les nouvelles tentatives Cloud Tasks via /api/tasks/fire-trigger au lieu d'appeler notifyUri directement depuis la file d'attente ? Comme userOAuthToken est de courte durée, l'intégration d'un jeton de support dans une charge utile de tâche mise en file d'attente risque d'échouer lors de tentatives ultérieures si le jeton expire. L'acheminement de chaque nouvelle tentative via le point de terminaison de votre worker Cloud Run permet à handleFireTriggerTask de lire le userOAuthToken actualisé le plus récent à partir de la collection Firestore studio_triggers et de réutiliser le même requestId pour une diffusion idempotente.

portal.js : interface utilisateur Support Quick Portal et répartiteur notifyUri avec solution de secours Cloud Tasks

Créez portal.js pour diffuser le portail Web et distribuer les envois de tickets à Google Workspace Studio avec une planification automatique des nouvelles tentatives Cloud Tasks :

• renderPortal (GET /) : interroge la collection Firestore studio_triggers pour afficher le nombre de déclencheurs Google Workspace Studio actifs enregistrés et diffuse le formulaire d'envoi de tickets HTML (y compris une case à cocher Simuler un échec temporaire pour tester les nouvelles tentatives Cloud Tasks).
• submitTicket (POST /api/submit-ticket) : itère sur tous les documents de déclencheur actifs dans studio_triggers et appelle fireTriggerDirect(). Si l'URL du déclencheur renvoie une réponse non 2xx, génère une erreur réseau ou si simulateFailure est activé, il met automatiquement en file d'attente une tâche de nouvelle tentative dans studio-trigger-retries à l'aide de enqueueTriggerRetry() et enregistre le ticket dans la collection Firestore support_tickets.

cat << 'EOF' > portal.js
import { triggersCollection, ticketsCollection } from './firestore.js';
import { fireTriggerDirect, enqueueTriggerRetry } from './tasks.js';

// Support Quick Portal UI
export async function renderPortal(req, res) {
  let activeCount = 0;
  try {
    const snapshot = await triggersCollection.get();
    activeCount = snapshot.size;
  } catch (err) {
    console.error('Error reading studio_triggers collection:', err.message);
  }

  res.status(200).send(`<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Support Quick Portal</title>
    <style>
      body { font-family: Arial, sans-serif; padding: 24px; max-width: 540px; margin: auto; color: #202124; }
      .badge { background: #e8f0fe; color: #1967d2; padding: 8px 12px; border-radius: 6px; font-size: 14px; margin-bottom: 16px; }
      label { font-weight: bold; display: block; margin-top: 16px; }
      .checkbox-label { font-weight: normal; margin-top: 14px; display: flex; align-items: center; gap: 8px; cursor: pointer; }
      .checkbox-label input { width: auto; margin: 0; }
      input, textarea { width: 100%; margin-top: 6px; padding: 10px; box-sizing: border-box; border: 1px solid #dadce0; border-radius: 4px; }
      button { background-color: #1a73e8; color: white; border: none; padding: 10px 18px; margin-top: 16px; font-weight: bold; cursor: pointer; border-radius: 4px; }
      button:hover { background-color: #1557b0; }
      #status { margin-top: 16px; font-weight: bold; }
    </style>
  </head>
  <body>
    <h2>Support Quick Portal</h2>
    <div class="badge">
      Active Google Workspace Studio triggers in Firestore (<code>studio_triggers</code>):
      <strong id="trigger-count">${activeCount}</strong>
    </div>
    <p>Submit a support ticket below to fire your Google Workspace Studio flow.</p>

    <label for="title">Ticket Title</label>
    <input type="text" id="title" placeholder="e.g. Database failure">

    <label for="description">Issue Description</label>
    <textarea id="description" rows="4" placeholder="Describe the issue..."></textarea>

    <label class="checkbox-label" for="simulateFailure">
      <input type="checkbox" id="simulateFailure">
      Simulate transient failure (enqueue in Cloud Tasks and retry notifyUri)
    </label>

    <button onclick="submitTicket()">Submit Ticket</button>
    <div id="status"></div>

    <script>
      async function submitTicket() {
        const title = document.getElementById('title').value.trim();
        const description = document.getElementById('description').value.trim();
        const simulateFailure = document.getElementById('simulateFailure').checked;
        const statusEl = document.getElementById('status');

        if (!title || !description) {
          statusEl.style.color = '#d93025';
          statusEl.textContent = 'Please fill out both fields.';
          return;
        }

        statusEl.style.color = '#188038';
        statusEl.textContent = 'Submitting ticket...';

        try {
          const res = await fetch('/api/submit-ticket', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ title, description, simulateFailure }),
          });
          const data = await res.json();
          if (data.ok) {
            if (data.tasksQueued > 0) {
              statusEl.textContent =
                'Ticket saved! Initial notifyUri call did not succeed; queued ' +
                data.tasksQueued +
                ' retry task(s) in Cloud Tasks.';
            } else {
              statusEl.textContent =
                'Ticket saved to Firestore! Fired ' +
                data.triggersFired +
                ' Google Workspace Studio trigger(s).';
            }
          } else {
            statusEl.style.color = '#d93025';
            statusEl.textContent = 'Error: ' + (data.error || 'Unknown error');
          }
        } catch (err) {
          statusEl.style.color = '#d93025';
          statusEl.textContent = 'Request failed: ' + err.message;
        }
      }
    </script>
  </body>
</html>`);
}

// Portal Form Submission -> Call notifyUri directly, or enqueue Cloud Task on failure
export async function submitTicket(req, res) {
  const title = req.body?.title || 'Untitled Ticket';
  const description = req.body?.description || '';
  const simulateFailure = Boolean(req.body?.simulateFailure);
  const results = [];
  let triggersFired = 0;
  let tasksQueued = 0;

  try {
    const snapshot = await triggersCollection.get();
    for (const doc of snapshot.docs) {
      const trigger = doc.data();
      if (!trigger.triggerId || !trigger.userOAuthToken) continue;

      const requestId =
        'req_' + Date.now() + '_' + Math.floor(Math.random() * 1000);

      let outcome = { ok: false, status: 503 };
      if (!simulateFailure) {
        try {
          outcome = await fireTriggerDirect(trigger, {
            title,
            description,
            requestId,
          });
        } catch (fetchErr) {
          console.error(
            `Direct trigger call failed for ${trigger.triggerId}:`,
            fetchErr.message
          );
          outcome = { ok: false, status: 0, error: fetchErr.message };
        }
      }

      if (outcome.ok) {
        triggersFired++;
        results.push({
          triggerId: trigger.triggerId,
          status: outcome.status,
          queuedRetry: false,
        });
      } else {
        const taskName = await enqueueTriggerRetry(req, {
          triggerId: trigger.triggerId,
          title,
          description,
          requestId,
          simulateFailure,
        });
        tasksQueued++;
        results.push({
          triggerId: trigger.triggerId,
          status: outcome.status,
          queuedRetry: true,
          taskName,
        });
      }
    }

    await ticketsCollection.add({
      title,
      description,
      triggersFired,
      tasksQueued,
      createdAt: new Date().toISOString(),
    });

    res.status(200).json({
      ok: true,
      triggersFired,
      tasksQueued,
      results,
    });
  } catch (err) {
    console.error('Error in /api/submit-ticket:', err.message);
    res.status(500).json({ ok: false, error: err.message });
  }
}
EOF

index.js : point d'entrée du serveur Express

Créez index.js pour relier vos routes de portail, le point de terminaison du worker de nouvelle tentative Cloud Tasks et les points de terminaison de Webhook Google Workspace Studio dans un serveur HTTP Express écoutant sur PORT (valeur par défaut 8080 sur Cloud Run) :

cat << 'EOF' > index.js
import express from 'express';
import { onConfigTrigger, onManageTrigger } from './starter.js';
import { onConfigUrgency, onExecuteUrgency } from './action.js';
import { renderPortal, submitTicket } from './portal.js';
import { handleFireTriggerTask } from './tasks.js';

const app = express();
app.use(express.json());

// Support Quick Portal routes
app.get('/', renderPortal);
app.post('/api/submit-ticket', submitTicket);

// Cloud Tasks retry worker route
app.post('/api/tasks/fire-trigger', handleFireTriggerTask);

// Google Workspace Studio Custom Starter Step webhooks
app.post('/onConfigTrigger', onConfigTrigger);
app.post('/onManageTrigger', onManageTrigger);

// Google Workspace Studio Custom Action Step webhooks
app.post('/onConfigUrgency', onConfigUrgency);
app.post('/onExecuteUrgency', onExecuteUrgency);

const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`Support Extension listening on port ${PORT}`);
});
EOF

4. Déployer sur Cloud Run et installer le module complémentaire

Dans cette étape, vous allez déployer le service Node.js sur Cloud Run, accorder des autorisations IAM pour l'appelant Google Workspace Add-ons et l'accès à l'exécution de Firestore, Cloud Tasks et Agent Platform, générer le fichier manifeste deployment.json et installer le déploiement du module complémentaire.

1. Déployez le service support-extension sur Cloud Run avec les variables d'environnement de votre projet, de votre collection Firestore et de votre file d'attente de tâches Cloud Tasks :

   gcloud run deploy support-extension \
     --source . \
     --region us-central1 \
     --allow-unauthenticated \
     --set-env-vars="GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project),FIRESTORE_TRIGGERS_COLLECTION=studio_triggers,FIRESTORE_TICKETS_COLLECTION=support_tickets,CLOUD_TASKS_QUEUE=studio-trigger-retries,CLOUD_TASKS_LOCATION=us-central1" \
     --quiet
   

2. Accordez roles/run.invoker sur le service Cloud Run au compte de service Google Workspace Add-ons afin que Google Workspace Studio puisse appeler vos points de terminaison de Webhook :

   ADDON_SA=$(gcloud workspace-add-ons get-authorization --format="value(serviceAccountEmail)")
   gcloud run services add-iam-policy-binding support-extension \
     --region=us-central1 \
     --member="serviceAccount:${ADDON_SA}" \
     --role="roles/run.invoker" \
     --quiet
   

3. Accordez roles/datastore.user (pour lire et écrire les collections Firestore studio_triggers et support_tickets), roles/cloudtasks.enqueuer (pour mettre en file d'attente les tâches de nouvelle tentative dans studio-trigger-retries) et roles/aiplatform.user (pour appeler Gemini sur Gemini Enterprise Agent Platform) au compte de service d'exécution Cloud Run :

   PROJECT_ID=$(gcloud config get-value project)
   PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)")
   RUNTIME_SA=$(gcloud run services describe support-extension --region=us-central1 --format="value(spec.template.spec.serviceAccountName)")
   RUNTIME_SA=${RUNTIME_SA:-"${PROJECT_NUMBER}[e-mail]"}
   
   gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member="serviceAccount:${RUNTIME_SA}" \
     --role="roles/datastore.user" \
     --condition=None \
     --quiet
   
   gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member="serviceAccount:${RUNTIME_SA}" \
     --role="roles/cloudtasks.enqueuer" \
     --condition=None \
     --quiet
   
   gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member="serviceAccount:${RUNTIME_SA}" \
     --role="roles/aiplatform.user" \
     --condition=None \
     --quiet
   

4. Récupérez l'URL Cloud Run déployée et générez le fichier manifeste deployment.json définissant les éléments supportTicketTrigger (workflowTrigger) et urgencyDetectorStep (workflowAction) :

   SERVICE_URL=$(gcloud run services describe support-extension --region=us-central1 --format="value(status.url)")
   
   cat << EOF > deployment.json
   {
     "oauthScopes": [
       "https://www.googleapis.com/auth/workspace.studio.trigger",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     "addOns": {
       "common": {
         "name": "Support Extension",
         "logoUrl": "https://www.gstatic.com/images/branding/productlogos/buganizer/v1/192px.svg"
       },
       "studio": {
         "flows": {
           "workflowElements": [
             {
               "id": "supportTicketTrigger",
               "state": "ACTIVE",
               "name": "New Support Ticket",
               "description": "Fires when someone submits a ticket in the Support Quick Portal.",
               "workflowTrigger": {
                 "inputs": [],
                 "outputs": [
                   {
                     "id": "ticketTitle",
                     "description": "Ticket Title",
                     "cardinality": "SINGLE",
                     "dataType": { "basicType": "STRING" }
                   },
                   {
                     "id": "ticketDescription",
                     "description": "Ticket Description",
                     "cardinality": "SINGLE",
                     "dataType": { "basicType": "STRING" }
                   }
                 ],
                 "onConfigFunction": "${SERVICE_URL}/onConfigTrigger",
                 "onManageFunction": "${SERVICE_URL}/onManageTrigger"
               }
             },
             {
               "id": "urgencyDetectorStep",
               "state": "ACTIVE",
               "name": "Detect Urgency",
               "description": "Evaluates the ticket description to detect High or Normal urgency.",
               "workflowAction": {
                 "inputs": [
                   {
                     "id": "ticketDescription",
                     "description": "Description to scan",
                     "cardinality": "SINGLE",
                     "dataType": { "basicType": "STRING" }
                   }
                 ],
                 "outputs": [
                   {
                     "id": "urgencyLevel",
                     "description": "Detected Urgency (High / Normal)",
                     "cardinality": "SINGLE",
                     "dataType": { "basicType": "STRING" }
                   }
                 ],
                 "onConfigFunction": "${SERVICE_URL}/onConfigUrgency",
                 "onExecuteFunction": "${SERVICE_URL}/onExecuteUrgency"
               }
             }
           ]
         }
       },
       "httpOptions": {
         "authorizationHeader": "SYSTEM_ID_TOKEN"
       }
     }
   }
   EOF
   

5. Créez (ou remplacez) et installez le déploiement du module complémentaire Google Workspace pour votre compte, puis affichez l'URL de votre portail Support Quick Portal :

   gcloud workspace-add-ons deployments create support-extension --deployment-file=deployment.json || \
     gcloud workspace-add-ons deployments replace support-extension --deployment-file=deployment.json
   gcloud workspace-add-ons deployments install support-extension
   echo "Support Quick Portal URL: ${SERVICE_URL}"
   

5. Tester vos étapes personnalisées et les nouvelles tentatives Cloud Tasks

1. Ouvrez Google Workspace Studio (actualisez l'onglet du navigateur s'il était déjà ouvert), puis cliquez sur Nouveau flux.
2. Cliquez sur Sélectionner un déclencheur > Support Extension > Nouvelle demande d'assistance.

   Résolution des problèmes OAuth client not found: si vous cliquez sur l'étape de déclencheur ou d'action et que le message OAuth client not found -- Is the OAuth consent screen configured? s'affiche, vérifiez que vous avez terminé la configuration du branding de Google Auth Platform et activé appsmarket-component.googleapis.com à l'étape 2. Après avoir activé le SDK Google Workspace Marketplace, la création automatique du client OAuth peut prendre une minute. Actualisez l'onglet Google Workspace Studio et réessayez.

3. Cliquez sur Ajouter une étape (+) > Support Extension > Detect Urgency. Dans le champ Description de la source , cliquez sur + Variables , puis sélectionnez Description du ticket.
4. Cliquez sur Ajouter une étape (+) et ajoutez une étape Chat > M'envoyer une notification dans Chat qui inclut les variables Titre du ticket, Niveau d'urgence et Description du ticket dans le message.
5. En haut à droite, activez le flux. Google Workspace Studio appelle immédiatement votre point de terminaison /onManageTrigger sur Cloud Run, qui écrit l'abonnement actif au déclencheur (y compris triggerId, notifyUri et userOAuthToken) dans la collection studio_triggers de Firestore.

   Important : Si votre flux n'est pas déclenché , votre déclencheur personnalisé ne reçoit des événements qu'après que Google Workspace Studio a appelé /onManageTrigger lorsque vous activez le flux. Si l'envoi d'un ticket dans le portail ne déclenche pas votre flux (ou si le portail affiche 0 déclencheurs actifs), vérifiez que le bouton d'activation du flux en haut à droite de Google Workspace Studio est activé , ou désactivez-le puis réactivez-le , puis actualisez le portail Support Quick Portal pour vérifier qu'au moins 1 déclencheur actif est stocké dans la collection Firestore studio_triggers.

6. Ouvrez l'URL de votre portail Support Quick Portal (https://support-extension-...run.app) dans un nouvel onglet, vérifiez que le portail affiche 1 déclencheur actif dans Firestore, puis envoyez deux tickets pour tester la classification Gemini 3.8 Flash (gemini-3.8-flash) :
   • Ticket à fort impact (Titre du ticket : London office lockout, Description du problème : All 500 employees in the London office are locked out of their workstations 20 minutes before the board presentation.) : même sans mots clés codés en dur tels que urgent ou blocker, gemini-3.8-flash classe ce ticket comme High urgence.
   • Ticket de routine (Titre du ticket : Conference room adapters, Description du problème : Could we order two extra HDMI adapters for the third-floor conference room next month?) : gemini-3.8-flash classe ce ticket comme urgence Normal.
7. Vérifiez dans Google Chat et dans l'onglet Activité de Google Workspace Studio que votre flux s'est exécuté pour les deux tickets avec Urgency Level: High et Urgency Level: Normal.
8. Testez la diffusion de nouvelles tentatives Cloud Tasks lorsque notifyUri échoue :
   1. Dans le portail Support Quick Portal, cochez la case Simuler un échec temporaire (mettre en file d'attente dans Cloud Tasks et réessayer notifyUri).
   2. Saisissez Titre du ticket : Checkout service outage et Description du problème : Production payment gateway is timing out for all customers, puis cliquez sur Envoyer le ticket.
   3. Notez que le portail répond immédiatement par : Ticket saved! Initial notifyUri call did not succeed; queued 1 retry task(s) in Cloud Tasks. (Ticket enregistré ! L'appel notifyUri initial n'a pas abouti. 1 tâche de nouvelle tentative a été mise en file d'attente dans Cloud Tasks.)
   4. En arrière-plan, Cloud Tasks exécute POST /api/tasks/fire-trigger. La première tentative de tâche (retryCount=0) simule un échec 503, ce qui entraîne un intervalle entre les tentatives de 10s (--min-backoff=10s) et une nouvelle tentative (retryCount=1) de Cloud Tasks, qui appelle notifyUri et réussit. Au bout de 10 à 15 secondes environ, vérifiez que votre notification Google Chat est arrivée.

6. Effectuer un nettoyage

Pour éviter que des frais permanents ne soient facturés sur votre compte Google Cloud, supprimez les ressources déployées dans Cloud Shell :

gcloud workspace-add-ons deployments uninstall support-extension
gcloud workspace-add-ons deployments delete support-extension --quiet
gcloud run services delete support-extension --region=us-central1 --quiet
gcloud tasks queues delete studio-trigger-retries --location=us-central1 --quiet
gcloud firestore databases delete --database="(default)" --quiet

7. Félicitations !

Vous avez créé, déployé et testé une extension HTTP Node.js pour Google Workspace Studio à l'aide de Firestore, Cloud Tasks, Cloud Run et Gemini 3.8 Flash sur Gemini Enterprise Agent Platform.

Points abordés

• Configurer un fichier manifeste de module complémentaire HTTP Google Workspace Studio (deployment.json) avec des éléments workflowTrigger et workflowAction.
• Conserver les abonnements workflowTrigger de Google Workspace Studio dans la collection Firestore studio_triggers et enregistrer les envois de portail dans support_tickets afin que les déclencheurs survivent à la mise à l'échelle et aux redéploiements de Cloud Run.
• Garantir la diffusion notifyUri (triggers.fire) avec Cloud Tasks (studio-trigger-retries) afin que les échecs HTTP temporaires soient automatiquement réessayés avec un intervalle exponentiel entre les tentatives à l'aide du dernier userOAuthToken de Firestore.
• Créer une étape workflowAction qui classe les tickets d'assistance avec Gemini 3.8 Flash (gemini-3.8-flash) sortie structurée sur Gemini Enterprise Agent Platform, avec une solution de secours résiliente basée sur la correspondance de mots clés.

Étapes suivantes

• Étendre Google Workspace Studio
• Créer des modules complémentaires Google Workspace HTTP
• Documentation Cloud Firestore
• Documentation Cloud Tasks
• Documentation Gemini Enterprise Agent Platform
• workspace-studio-node-addon Compétence d'agent sur GitHub