Weegloo Docs - Script

Imaginez que vous gérez une boutique de vêtements en ligne. Rédiger à la main une description détaillée attrayante pour chaque produit que vous mettez en ligne est fastidieux. Vous aimeriez donc qu'il suffise de saisir le nom du produit et quelques mots-clés pour qu'une IA rédige la description à votre place. Mais pour appeler ce service d'écriture par IA, il faut une clé secrète (access token, la clé par laquelle le service externe vérifie qu'il s'agit bien d'un utilisateur qui a payé). Si vous placez cette clé dans le site web que voit le client (le navigateur), n'importe qui peut l'en extraire, et elle fuite. Avec une clé ainsi divulguée, un tiers pourrait utiliser ce service à sa guise et vous en faire supporter les frais.

Il vous faut donc quelque chose qui garde la clé cachée, hors de portée du regard du client, et qui appelle l'IA à la place du site web avant d'en verser le résultat dans le produit. C'est cela, un Script. Un Script, c'est la description, dans l'ordre, des tâches à accomplir, du type « appelle l'IA avec cette clé, puis verse le texte reçu dans la description détaillée de ce produit ». On ne l'écrit pas en code, mais dans un format défini (JSON, une façon de noter des données où les éléments et les valeurs s'écrivent entre accolades). Le site web n'a qu'à appeler ce Script par Internet, et la clé, dissimulée à l'intérieur du Script, reste invisible pour le client.

On peut le comparer à une recette que l'on affiche d'avance dans la cuisine. Lorsqu'un client commande ce plat (lorsque le site web appelle le Script), la cuisine (WEEGLOO) le prépare dans l'ordre indiqué par la recette et sert le plat terminé. Le patron n'a fait qu'écrire et afficher la recette ; il ne cuisine pas lui-même à chaque commande. Cette page examine ce qu'est un Script, à quoi il ressemble et ce qu'il renvoie lorsqu'on l'appelle, puis en illustre la forme à travers l'exemple du Script « Remplir la description du produit » de la boutique de vêtements. À la fin, elle montre aussi comment faire en sorte que ce Script s'exécute de lui-même au moment où un produit est enregistré.

Ce que Script fait à votre place

Même pour une seule tâche comme remplir la description d'un produit, il y a, en coulisses, plusieurs choses à faire. Il faut vérifier que l'appelant en a l'autorisation, contrôler que les valeurs envoyées sont correctes, appeler le service d'IA externe avec la clé dissimulée, placer le résultat reçu à l'endroit voulu (la description détaillée du produit), puis renvoyer une réponse. Autrefois, il fallait créer soi-même le programme intermédiaire qui accomplit ces tâches, le déployer sur un serveur et le maintenir. L'objectif de Script est de prendre en charge ces tâches en les inscrivant toutes au même endroit, sans code.

Un Script correspond à un seul guichet d'appel. Un guichet que le site web peut appeler par Internet correspond à un Script. Le mode utilisé pour l'appeler (method) détermine quel Script est exécuté.
Les tâches sont disposées de haut en bas. Dans un Script, vous inscrivez dans l'ordre les actions à exécuter. Elles s'exécutent tour à tour depuis le haut, et chaque action reprend le résultat de la précédente.
Vous choisissez et combinez des actions prédéfinies. Vous n'insérez pas n'importe quel code : vous choisissez et alignez des actions déjà prêtes (créer, lire, modifier et supprimer des ressources, appeler un service externe, mémoriser une valeur, vérifier une condition, répéter, etc.).

La définition qui décrit ce qu'il faut faire

Un Script se compose d'une « définition » qui fixe quatre choses.

Le mode d'appel (method) : la manière utilisée pour appeler ce Script. C'est l'un de Get, Post, Put, Patch, Delete ; lors de l'appel, cette valeur sert à identifier de quel Script il s'agit.
Le mode d'exécution (executionMode) : s'exécuter immédiatement à l'endroit de l'appel (Sync) ou s'exécuter en arrière-plan (Async). Traité plus bas dans Exécution immédiate et exécution en arrière-plan.
Les tâches à accomplir (statements) : la liste des actions à exécuter de haut en bas. Il en faut au moins une.
La validation de l'entrée (payloadSchema, facultatif) : le format selon lequel vérifier, avant l'exécution, l'entrée envoyée avec l'appel. Si vous le définissez, toute entrée non conforme au format est rejetée sans être exécutée.

Prenons l'exemple du Script « Remplir la description du produit » de la boutique de vêtements. Ce que ce Script traite, c'est un produit doté d'un nom et de mots-clés. L'entrée transmise par le site web (lors de l'exécution automatique que nous verrons plus loin, c'est le produit enregistré qui est transmis tel quel) a cette forme.

{
  "sys": { "id": "3trmXRMKq7bd0Prbef1... (numéro du produit)" },
  "fields": {
    "productName": { "fr-FR": "Gobelet isotherme en inox 500 ml" },
    "keywords":    { "fr-FR": "isolation thermique, légèreté, camping" }
  }
}

Voici la définition d'un Script qui reçoit ce produit, génère la description détaillée à l'aide d'une IA externe, puis remplit la description détaillée (body) de ce produit.

{
  "method": "Post",
  "executionMode": "Async",
  "statements": [
    { "type": "Http", "method": "POST",
      "url": "https://api.ai-writer.example.com/v1/generate",
      "headers": [
        { "key": "Authorization", "value": "Bearer <access token secret>", "secret": true }
      ],
      "body": {
        "product":  "{ /payload/fields/productName/fr-FR }",
        "keywords": "{ /payload/fields/keywords/fr-FR }"
      },
      "name": "gen" },
 
    { "type": "ResourcePatch", "resource": "Content",
      "target": { "sys": { "id": "{ /payload/sys/id }" } },
      "fields": { "body": { "fr-FR": "{ /gen/body/text }" } },
      "publish": true },
 
    { "type": "Return", "value": { "id": "{ /payload/sys/id }" }, "statusCode": 200 }
  ]
}

La première action (Http) appelle le service d'IA externe avec la clé dissimulée. Si vous ajoutez secret: true à l'en-tête qui contient la clé, cette valeur reste invisible pour le client et n'est révélée qu'au tout dernier moment, juste avant l'appel. Le résultat reçu est rangé sous le nom gen.
La deuxième action (ResourcePatch) remplit uniquement la description détaillée (body) de ce produit avec le texte reçu précédemment ({ /gen/body/text }). Elle ne touche pas aux autres valeurs du produit.
On utilise les espaces réservés { /… } qui font passer une valeur à l'étape suivante. { /payload/fields/productName/fr-FR } désigne le nom du produit transmis, { /payload/sys/id } le numéro de ce produit, et { /gen/body/text } le texte renvoyé par l'IA.
La dernière action (Return) renvoie le numéro du produit dont la description vient d'être remplie.
La raison pour laquelle les valeurs d'un Content s'écrivent par langue, comme dans { "fr-FR": … }, l'ensemble des types d'actions que l'on peut placer dans statements, ainsi que la syntaxe des espaces réservés, des conditions et des calculs sont traités dans Expressions de valeur et Catalogue des Statement.

Ce que l'appel renvoie

À la toute fin, un Script renvoie à l'appelant la valeur de l'action Return. La réponse renvoyée contient ce qui suit.

requestId : un numéro d'identification qui désigne cette exécution.
durationMs : le temps qu'a duré l'exécution (en millisecondes).
statusCode : le code de statut du Return atteint (200 si vous n'en définissez pas).
return ou error : la valeur renvoyée par Return. Elle figure normalement dans return ; si vous l'avez marquée comme une erreur, elle figure dans error. Les deux n'apparaissent jamais ensemble.

Cela dit, comme « Remplir la description du produit » appelle une IA externe, il s'exécute en arrière-plan (voir plus bas Exécution immédiate et exécution en arrière-plan). Aussi, lorsqu'on l'appelle, seuls un 202 et un requestId reviennent d'abord immédiatement, pour signifier « bien reçu », et la réponse ci-dessus se récupère un peu plus tard en la redemandant (polling) à l'aide de ce requestId. Une fois terminée, la réponse a cette forme.

{
  "requestId": "3trmXRMZ8kqLb2Prdf1eYc0axWnKv",
  "durationMs": 1840,
  "statusCode": 200,
  "return": { "id": "3trmXRMKq7bd0Prbef1... (numéro du produit)" }
}

Grâce à l'id de ce return, le site web peut retrouver le produit dont la description vient d'être remplie et afficher au client la nouvelle description détaillée.

Si un Script se termine sans atteindre de Return, la réponse revient avec le seul statusCode à 200, sans return ni error. Les règles détaillées pour fixer le corps de la réponse et le code de statut avec Return sont traitées dans Return dans le Catalogue des Statement.

Exécution immédiate et exécution en arrière-plan

Un Script peut s'exécuter de deux manières, que vous fixez avec le executionMode de la définition.

Exécution immédiate (Sync) : l'exécution a lieu sur-le-champ, à l'endroit de l'appel, et la réponse terminée est renvoyée aussitôt. Cela convient aux tâches qui se terminent vite, sans appel externe.
Exécution en arrière-plan (Async) : l'exécution a lieu en arrière-plan. À l'appel, seuls un 202 et un requestId sont renvoyés immédiatement, pour signifier « bien reçu », et le résultat réel se récupère plus tard en le redemandant (polling) à l'aide de ce requestId.

Il y a une règle. Si un Script contient ne serait-ce qu'une action qui appelle un service externe ou qui reçoit un fichier pour l'intégrer comme Media, il doit obligatoirement s'exécuter en arrière-plan. Comme « Remplir la description du produit » appelle lui aussi une IA externe, il s'exécute en arrière-plan. Si vous tentez de l'enregistrer en exécution immédiate, l'enregistrement est refusé. C'est pour ne pas retenir l'appelant même lorsque la réponse externe tarde.

Le temps disponible pour l'exécution est lui aussi limité. Il est par défaut de 10 secondes pour l'exécution immédiate et de 60 secondes pour l'exécution en arrière-plan. Les règles détaillées, comme la façon d'effectuer le polling ou les actions qui imposent l'exécution en arrière-plan, sont traitées dans Sémantique d'exécution, contraintes et sécurité.

Qui crée un Script

Plutôt que d'écrire à la main, une à une, des actions complexes, Script a été conçu pour être créé par un agent IA ou un programme. Si vous demandez de vive voix à un agent IA « crée-moi un guichet qui remplit la description des produits », l'agent rédige à votre place une définition comme celle vue plus haut. Une simple phrase suffit ainsi à faire naître un guichet qui travaillera derrière le site web.

Le déroulé détaillé de la création d'un Script avec un agent IA est traité dans Créer un backend rien qu'en le demandant.

Une fois créé, un Script se consulte et se gère à la main depuis l'écran de gestion (le studio de contenu). Vous y vérifiez son nom et sa définition, et vous le modifiez ou le supprimez si besoin. Ce qui appelle réellement le Script, c'est le site web ou l'application que voit le client (le frontend). Avec l'identité d'un membre inscrit au produit (ServiceUser), on peut seulement exécuter un Script, mais ni le créer ni le modifier.

En quoi cela diffère de Webhook

Script et Webhook sont tous deux des dispositifs qui relient à l'extérieur, mais le sens de l'appel est inversé.

Le Webhook réagit de lui-même dès qu'un changement défini se produit (comme l'enregistrement d'un produit). Même sans que personne l'appelle, il se met en marche de lui-même dès que l'événement survient. En revanche, il ne renvoie pas de résultat à l'appelant.
Le Script est un guichet que le site web appelle directement quand il en a besoin. Il ne s'exécute que si on l'appelle, et le résultat de cette exécution est renvoyé immédiatement, ou par polling s'il s'agit d'une exécution en arrière-plan.

« Lorsque le patron appuie sur le bouton "Remplir la description", appeler l'IA, récupérer la description détaillée et la renseigner » est une tâche où l'appelant attend le résultat : c'est donc un Script qui convient ; « lorsqu'un produit est enregistré, quelque chose se produit automatiquement » est une tâche qui réagit à un événement : c'est donc un Webhook qui convient. Et les deux peuvent s'employer ensemble, comme nous le voyons juste après.

Remplir la description automatiquement dès l'enregistrement

Jusqu'ici, le patron appelait le Script directement, en appuyant sur le bouton « Remplir la description ». On peut aller un cran plus loin : sans même appuyer sur un bouton, faire en sorte que le Script s'exécute de lui-même au moment où un produit est enregistré. C'est que le Webhook capte cet événement et appelle notre Script à notre place.

Voici le déroulement.

Le patron enregistre un produit. Il ne renseigne alors que le nom du produit et les mots-clés, et laisse la description détaillée vide.
Le Webhook détecte l'événement d'enregistrement d'un nouveau produit.
Le Webhook transmet le produit qui vient d'être enregistré, tel quel, à notre Script « Remplir la description du produit » et l'exécute.
Le Script génère la description détaillée à l'aide de l'IA externe et remplit la description détaillée (body) de ce produit.
Peu après, la description détaillée du produit se trouve remplie d'elle-même.

Ici, le Script utilisé est exactement le même que précédemment. Seul change ce qui déclenche l'appel. Au lieu d'un bouton, c'est l'événement « un produit a été enregistré » qui l'appelle. Comme le produit enregistré devient tel quel l'entrée du Script, celui-ci saisit ce produit grâce à { /payload/sys/id } et en remplit la description détaillée.

Du côté du Webhook, il y a trois choses à définir. À quel événement réagir (lorsqu'un nouveau produit est enregistré), à quels produits seulement réagir (en le limitant par type de produit), et quoi faire (appeler notre Script au lieu de prévenir une adresse externe).

On pourrait craindre que la description détaillée remplie par le Script déclenche à son tour l'événement « un produit a changé », et ainsi de suite sans fin. Ce n'est pas le cas. L'écriture effectuée par un Script ne déclenche pas de nouvel événement tant qu'on ne l'active pas expressément, et la plateforme empêche elle aussi les boucles sans fin.

La configuration détaillée pour établir ce lien est traitée dans Webhook.

Quand Script est particulièrement utile

Si la tâche se limite à signaler à l'extérieur qu'« il s'est passé telle chose », un Webhook suffit. Mais s'il faut appeler un service externe puis, au vu de son résultat, décider de la suite et la traiter, alors il faut un Script qui réunit tout ce déroulé en un seul endroit.

Prenons l'exemple d'une fonctionnalité payante de génération d'images par IA. Lorsqu'un client demande la génération d'une image, les opérations suivantes doivent se dérouler dans l'ordre.

Vérifier si le client dispose de suffisamment de crédits. S'il en manque, s'arrêter là et lui signaler « Crédits insuffisants ».
S'il en a assez, commencer par déduire les crédits correspondant au coût.
Appeler le service externe d'IA pour générer l'image.
Enregistrer l'image générée sous forme de Content.
En cas de problème à l'étape 3 ou 4, restituer les crédits qui viennent d'être déduits.

Un Webhook peut certes signaler à l'extérieur qu'« une requête est arrivée », mais il ne peut pas, comme ici, examiner le résultat pour déduire des crédits ou revenir en arrière en cas d'échec. Enchaîner plusieurs étapes selon des conditions et défaire les étapes précédentes en cas d'échec, c'est Script qui s'en charge. Voici les cas où Script joue pleinement son rôle.

Quand la suite du traitement dépend d'un résultat : en fonction de la réponse renvoyée par le service externe, Script décide sur-le-champ s'il faut enregistrer, déduire ou revenir en arrière.
Quand des requêtes simultanées ne doivent pas entrer en conflit : même si un même client envoie deux requêtes coup sur coup, les crédits ne doivent pas être déduits deux fois. Après avoir lu la valeur et juste avant de l'enregistrer, Script vérifie, à l'aide de la version, qu'« aucune autre requête n'a modifié cette valeur entre-temps », et s'arrête en cas de conflit.
Quand une autorisation dont l'appelant ne dispose pas est nécessaire : le client n'a pas l'autorisation de modifier lui-même directement son solde de crédits. Si la déduction s'effectue malgré tout en toute sécurité, c'est que Script s'exécute par délégation des autorisations de son créateur. Il suffit d'accorder à l'appelant l'autorisation d'exécuter le Script. Cette délégation est traitée en détail plus bas, dans Autorisations d'exécution et de gestion.

La manière d'écrire cet exemple sous la forme d'une véritable définition de Script est traitée dans le Cookbook (Exemples pratiques), dans l'exemple qui vérifie, déduit et restitue des crédits.

Autorisations d'exécution et de gestion

Pour exécuter ou gérer un Script, le rôle (SpaceRole) doit disposer de l'autorisation correspondante.

Exécution : pour appeler un Script, le rôle doit disposer de l'autorisation d'exécution de Script (Execute). À défaut, l'exécution est bloquée.
Gestion : pour créer, modifier et supprimer un Script, il faut respectivement les autorisations de création, de modification et de suppression.

Lors de l'exécution d'un Script, une seule chose est vérifiée : l'appelant possède-t-il l'autorisation d'exécution (Execute). Les actions individuelles alignées dans le Script ne font pas l'objet d'une vérification d'autorisation distincte au moment de l'exécution. C'est comme lorsqu'on appelle un programme autorisé à s'exécuter : on ne regarde que l'autorisation de lancer ce programme, sans redemander l'autorisation pour chacune des tâches qu'il accomplit en son sein.

En contrepartie, l'autorisation des actions individuelles est vérifiée à l'avance, non pas à l'exécution, mais au moment d'enregistrer le Script. Pour que l'enregistrement aboutisse, son créateur doit réellement posséder les autorisations sur les opérations Content et Media que manipulent les actions du Script. Par exemple, comme le Script « Remplir la description du produit » modifie la description détaillée du Content produit, si son créateur n'a pas l'autorisation de modifier les produits, l'enregistrement est refusé. Un Script contenant une action non autorisée n'est tout simplement pas enregistré.

Vu ainsi, exécuter un Script revient à agir par délégation des autorisations de son créateur. Même une opération que l'appelant ne pourrait pas faire par lui-même se produit bel et bien via le Script, dès lors que son créateur, lui, peut la faire. C'est pourquoi, en créant un Script, il faut décider avec soin des actions qu'on y place. Les autorisations de son créateur définissent l'étendue de ce que ce Script peut faire.

La manière d'attribuer des autorisations à un rôle est traitée dans Rôles et permissions.

À savoir

Il n'y a pas de publication. Un Script n'est pas une ressource du type que l'on publie pour la livrer aux visiteurs : c'est un guichet que l'on crée dans l'écran de gestion et que le site web appelle pour l'utiliser. Aussi, contrairement aux Content et Media, il n'a pas d'état publié ni dépublié, et il est utilisable dès sa création. Chaque modification ne fait qu'incrémenter sa version d'un cran ; et à la suppression aussi, il s'efface directement, sans étape préalable comme la dépublication.
Le nombre est limité. Comme Script est soumis à facturation, le nombre qu'une même Organization peut posséder est fixé selon la formule tarifaire (Free 3, Basic 10, Pro 50, Enterprise illimité). Une fois la limite atteinte, vous ne pouvez plus créer de nouveau Script ; supprimer un Script inutilisé libère de nouveau une place.

Gérer dans le studio de contenu

Une fois créé, un Script se consulte et se gère dans l'écran Script du studio de contenu. En cliquant sur Scripts dans le menu de gauche, vous obtenez la liste des Script créés jusqu'ici. Chaque ligne affiche le nom, le mode d'appel (Méthode HTTP), le Script ID qui désigne le Script, le lieu d'exécution (Mode d'exécution) et la date de dernière modification.

Écran de la liste des Script. Le Script « Remplir la description du produit » apparaît sur une ligne, avec la méthode HTTP POST et le mode d'exécution Async

La définition est en général rédigée à votre place par un agent IA, mais vous pouvez aussi la créer directement depuis cet écran. Un nouveau Script se crée avec le bouton Créer en haut à droite de la liste.

Cliquez sur le bouton Créer en haut à droite de la liste.
Dans le champ Nom, saisissez Remplir la description du produit.
Choisissez la Méthode HTTP correspondant au mode d'appel de ce Script (ici, POST).
Choisissez le Mode d'exécution Async (exécution en arrière-plan). Comme ce Script appelle une IA externe, il doit obligatoirement s'exécuter en arrière-plan.
Dans le champ Statement, insérez la définition qui décrit les tâches. Il suffit d'y insérer telle quelle la définition de l'exemple « Remplir la description du produit » ci-dessus.

Écran de création d'un nouveau Script. Nom « Remplir la description du produit », méthode HTTP POST, mode d'exécution Async, définition saisie dans le champ Statement

Si vous voulez vérifier, avant l'exécution, l'entrée à envoyer lors de l'appel, activez la Validation du Payload de Payload Schema et inscrivez le format à vérifier. Une fois tout rempli, cliquez sur le bouton Enregistrer en haut à droite.

En cliquant sur un Script dans la liste, son écran de détail s'ouvre. Vous y vérifiez son nom et sa définition, et vous pouvez aussi voir l'adresse à laquelle appeler ce Script (Execute URL). Après avoir modifié la définition, Enregistrer fait monter la version d'un cran ; un Script que vous n'utilisez plus se supprime avec Supprimer.

Écran de détail du Script « Remplir la description du produit ». Le nom, la méthode HTTP, le mode d'exécution, l'ID, l'Execute URL ainsi que la définition Statement sont visibles

Et ensuite

Présentation de Script : aborde la structure de plus haut niveau de la définition qui compose un Script, ses règles d'exécution et l'ensemble des documents de syntaxe.
Catalogue des Statement : aborde les types et les champs des actions que l'on peut placer dans statements (créer, lire, modifier et supprimer des ressources, appeler un service externe, conditions, boucles, etc.).
Webhook : aborde la manière de réagir automatiquement lorsqu'un changement défini se produit, comme relier un Script pour qu'il s'exécute de lui-même dès qu'un produit est enregistré.