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 n'avoir à saisir que le nom du produit et quelques mots-clés, et laisser une IA rédiger la description détaillée à 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 trois 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.
• 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",
  "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.

« Remplir la description du produit » s'exécute lui aussi sur place lorsqu'on l'appelle, et la réponse ci-dessus revient aussitôt. Comme il contient toutefois une action qui appelle une IA externe, la réponse peut mettre quelques secondes à arriver. Le temps disponible pour une seule exécution est traité plus bas dans Le temps alloué à une exécution. La réponse qui revient 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.

Le temps alloué à une exécution

Un Script s'exécute sur place, à l'endroit de l'appel. L'appelant reçoit directement le résultat de cette exécution dans la réponse. Il n'existe pas de déroulé où l'on redemanderait le résultat plus tard pour le récupérer.

Le temps disponible pour une seule exécution fait l'objet d'un budget. Il est de 30 secondes par défaut. Si le Script contient une action qui appelle un service externe, ce budget augmente du temps d'attente fixé pour cette action. Même ainsi augmenté, il va jusqu'à 180 secondes au maximum.

Une action qui répète quelque chose consomme beaucoup de budget. En effet, le budget retenu correspond au temps d'attente fixé pour l'action intérieure à la boucle, multiplié par le nombre de répétitions. Si vous fixez un grand nombre de répétitions, le budget est calculé d'autant plus grand.

Une exécution qui dépasse le temps imparti s'interrompt là. Comme « Remplir la description du produit » appelle une IA externe une seule fois, le budget de ce Script correspond aux 30 secondes par défaut plus le temps d'attente de cet unique appel.

Le budget retenu pour chaque action, ainsi que les autres contraintes qui s'appliquent à l'exécution, sont traités 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.

« 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. C'est l'objet de la section qui suit.

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.

1. 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.
2. Le Webhook détecte l'événement d'enregistrement d'un nouveau produit.
3. Le Webhook transmet le produit qui vient d'être enregistré, tel quel, à notre Script « Remplir la description du produit » et l'exécute.
4. 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.
5. 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.

Certains Script peuvent ainsi être configurés pour ne s'exécuter que par l'intermédiaire d'un Webhook, tout en interdisant qu'on les appelle directement par leur adresse depuis l'extérieur. Ce Script ne réagit alors qu'aux événements définis, et un appel direct est refusé. La manière de le configurer est traitée dans Ressource Script et endpoints.

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.

1. 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 ».
2. S'il en a assez, commencer par déduire les crédits correspondant au coût.
3. Appeler le service externe d'IA pour générer l'image.
4. Enregistrer l'image générée sous forme de Content.
5. 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. Vous n'avez à accorder à l'appelant que 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 qui contient une action non autorisée n'est pas enregistré, dès le départ.

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 10, Basic 30, Pro 100, 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 de la liste affiche le nom, l'Endpoint (le mode d'appel et l'adresse y sont affichés ensemble), l'autorisation ou non de l'appel anonyme (Anonyme), la date de modification et l'auteur de la modification.

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.

1. Cliquez sur le bouton Créer en haut à droite de la liste.
2. Dans le champ Nom, saisissez Remplir la description du produit.
3. Choisissez la Méthode HTTP correspondant au mode d'appel de ce Script (ici, POST).
4. Dans le champ Statement, insérez la définition qui décrit les tâches. Vous pouvez y insérer telle quelle la définition de l'exemple « Remplir la description du produit » ci-dessus.

L'écran de création comporte en outre les champs Autoriser l'appel direct (une fois désactivé, le Script ne peut plus être appelé par son URL d'appel et ne s'exécute que par l'intermédiaire d'un Webhook ou d'un Scheduler ; activé par défaut), Autoriser l'appel anonyme (une fois activé, une adresse d'appel anonyme est créée en plus, par laquelle un tiers peut l'appeler sans connexion Weegloo ; désactivé par défaut), et URL d'appel (deux lignes, Standard et Anonyme, vides pour l'instant puisqu'elles ne sont fixées qu'à l'enregistrement).

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 Créer en haut à droite.

En cliquant sur un Script dans la liste, son écran de détail s'ouvre. Cet écran de détail se divise en deux onglets, Log d'exécution et Paramètres, et à la première ouverture c'est Log d'exécution qui s'affiche. Dans l'onglet Paramètres, vous vérifiez le nom et la définition, et à droite vous voyez ensemble le numéro (ID) de ce Script, sa Version et ses Modifications (date de création, auteur de la création, date de modification, auteur de la modification). 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.

L'onglet Log d'exécution accumule, une ligne à la fois, les enregistrements des exécutions réelles de ce Script. Chaque ligne affiche l'heure d'exécution (Exécuté le), ce qui a lancé cette exécution (Déclencheur), le Résultat, la Durée et l'ID de requête qui désigne cette exécution. La case Résultat en haut permet de n'afficher que les exécutions réussies ou que celles en échec, et Actualiser Les Logs recharge les enregistrements jusqu'à celui de l'exécution qui vient d'avoir lieu.

Les enregistrements ne sont pas conservés longtemps. Une exécution réussie est effacée d'elle-même au bout d'une heure, une exécution en échec au bout de trois jours. Comme les réussies disparaissent en premier, il arrive que la liste semble ne contenir que des échecs.

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é.