Comment appeler une API externe depuis Workspace Studio

Un flux de travail Google Workspace Studio peut nécessiter des données provenant de sources externes à Gmail, Drive ou Chat : le statut d’une commande, un numéro issu d’une base de données ou une réponse d’un outil interne. Pour récupérer ces données ou envoyer des informations à un autre service, vous pouvez ajouter l’étape suivante : Envoyer un webhookCela effectue une requête HTTP vers l'adresse d'une API que vous avez spécifiée.

Il n'est pas nécessaire de configurer l'appel de fonction Gemini pour effectuer cette requête. Dans Workspace Studio, le flux exécute l'étape webhook et reçoit la réponse. Ensuite, si vous le jugez utile, vous pouvez transmettre cette réponse à une autre étape pour la résumer, en extraire des données ou communiquer le résultat.

Ce dont vous avez besoin avant de vous connecter à une API

La première étape consiste à vérifier que votre organisation peut utiliser les webhooks. Cette fonction se trouve dans aperçu limité Cette fonction est désactivée par défaut. Un administrateur doit se connecter. Applications > Google Workspace > Workspace Studio > Paramètres des webhooks et l'activer pour l'unité organisationnelle correspondante.

Dans certaines versions, l'administrateur peut également limiter les connexions à une seule liste des domaines et URL autorisésSi l'étape apparaît dans Studio mais ne parvient pas à communiquer avec votre API, vérifiez que l'adresse de destination est autorisée. Par ailleurs, par défaut, les actions impliquant des webhooks nécessitent une vérification et une confirmation de l'utilisateur avant leur exécution.

Du service externe, vous devez connaître son URL, les méthodes HTTP qu'il prend en charge et le format de données attendu. Vérifiez également son mode d'authentification : une API publique en lecture seule a des exigences différentes d'une API privée nécessitant des jetons ou des en-têtes spécifiques.

Comment appeler une API depuis Workspace Studio, étape par étape

Entrer studio.workspace.google.com Créez ensuite un flux de travail avec le déclencheur souhaité. Par exemple, vous pouvez le démarrer lorsqu'un e-mail répondant à certaines conditions arrive. Suivez ensuite ces étapes :

1. Presse Ajouter une étape et sélectionnez Envoyer un webhook.
2. Entrez dans URL complète de l'API, y compris le préfixe https://L'adresse doit être fixe : ce champ ne prend pas en charge les variables de flux.
3. Sélectionnez la méthode HTTP. OBTENIR Il est utilisé pour interroger des données ; POSTEpour les envoyer ou créer un enregistrement. Ils sont également disponibles PUT, PATCH et DELETE.
4. Si l'API requiert un corps, écrivez-le dans le champ de contenu ou charge utileGoogle recommande d'utiliser JSON lorsque le service destinataire l'attend.
5. Faites un exécution des testsVérifiez le résultat et activez le flux une fois que vous avez vérifié son bon fonctionnement.

N'oubliez pas que le test effectuer l'actionSi vous configurez une requête POST pour créer un enregistrement ou une requête DELETE pour le supprimer, utilisez d'abord un environnement de test ou des données que vous pouvez modifier sans problème.

Exemple : envoi d'une notification à un outil externe

Imaginez que votre équipe dispose d'une API qui crée des alertes dans https://api.ejemplo.com/v1/avisosCette adresse est illustratifVous devrez le remplacer par celui de votre service. Si sa documentation indique qu'il accepte les requêtes POST et un corps JSON, vous pouvez configurer l'étape avec un contenu comme celui-ci : {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Vous pouvez également insérer un variable de débit Dans le corps du message, par exemple, pour inclure l'objet de l'e-mail qui l'a déclenché. Faites-le depuis le sélecteur de variables de Studio et vérifiez le résultat : si le texte inséré contient des guillemets ou d'autres caractères spéciaux, le JSON risque d'être malformé. Les variables peuvent être utilisées dans le contenu, mais… pas dans le champ URL.

Pour récupérer des données, sélectionnez GET et saisissez une URL fixe contenant déjà les paramètres nécessaires. Workspace Studio ignorera tout contenu saisi dans le corps de la requête GET.

Que faire de la réponse de l'API

L'étape du webhook laisse le Réponse du service sous forme de texte dans une variable disponible pour les étapes suivantes. Vous pouvez l'utiliser pour envoyer une notification, rédiger un résumé ou demander à une étape d'IA d'extraire des données spécifiques.

Par exemple, si l'API renvoie le statut d'une commande, l'étape suivante peut communiquer ce statut à l'équipe. Sélectionnez explicitement la variable contenant la réponse : les étapes suivantes ne reçoivent pas automatiquement toutes les informations précédentes. Il est conseillé de tester le contenu renvoyé avant de rédiger des instructions qui en dépendent.

Si l'API requiert une authentification ou une logique plus complexe

La configuration de base documentée pour Envoyer un webhook Elle comprend l'URL, la méthode et un corps facultatif. Si votre intégration nécessite l'obtention d'un jeton OAuth, la construction d'une URL avec des paramètres variables, l'ajout d'en-têtes spécifiques ou la transformation d'une réponse avant de poursuivre, vérifiez si cette étape couvre ces exigences.

Lorsque cela s'avère insuffisant, une option consiste à développer un Étape personnalisée pour Workspace Studio via un plugin. Dans une implémentation Google Apps Script, le service UrlFetchApp Elle permet d'effectuer des requêtes auprès d'API externes et de traiter les réponses JSON. Cette solution nécessite un développement et une configuration appropriée des permissions ; elle n'est pas nécessaire pour les requêtes simples que l'étape native peut déjà gérer.

Évitez de coller des clés privées dans les champs visibles du flux ou de les intégrer dans une URL partagée. Avant d'envoyer des données depuis Gmail, Chat ou Agenda, vérifiez quelles informations le service externe recevra et s'il est autorisé à les traiter.

Comment localiser les erreurs dans un webhook

Si la connexion échoue, ouvrez l'onglet Activité Vous pouvez y consulter l'erreur complète et la réponse du serveur de destination. Ces informations permettent de distinguer un problème de configuration de Studio d'une requête rejetée par l'API.

• L'étape n'apparaît pas : Vérifiez auprès de votre administrateur si les webhooks sont activés pour votre unité organisationnelle.
• L'URL est bloquée : Vérifiez la liste des adresses autorisées, si votre édition utilise cette restriction.
• Erreur 400 : Vérifiez le format du corps de la requête et les champs requis par l'API.
• Erreur 401 ou 403 : Veuillez vérifier les autorisations et la méthode d'authentification requises par le service.
• Erreur 429 : Vérifiez si vous avez dépassé la limite de requêtes pour l'API cible.
• Erreur 500 : Vérifiez le statut et les enregistrements du service qui reçoit la demande.

Il convient également de tenir compte des limitations générales de Workspace Studio : il prend actuellement en charge jusqu’à 25 flux par utilisateur y 20 étapes par fluxDe plus, une limite d'exécution combinée est réinitialisée toutes les 24 heures. Si plusieurs flux s'arrêtent, examinez leur activité avant d'imputer la panne à l'API.

Pour la plupart des connexions HTTP simples, la procédure est directe : activer le webhook, configurer une URL fixe et la méthode appropriée, tester la requête et utiliser la réponse pour les étapes suivantes. Si l’intégration requiert une authentification avancée ou la transformation de données par le biais de code, il est alors judicieux de prévoir une étape personnalisée.