Ressource Script et endpoints

Script est un endpoint backend déclaratif qu'un frontend appelle via HTTP (son concept et sa structure de niveau supérieur sont traités dans Aperçu de Script). Cette page traite la structure sys et les propriétés de corps de la ressource Script, la spécification des endpoints HTTP qui permettent d'écrire et d'exécuter un Script, ainsi que ScriptLog, l'enregistrement d'une exécution.

La création et la gestion d'un Script (lister, lire, créer, modifier, supprimer) se font sur CMA (https://cma.weegloo.com/v1). L'exécution est prise en charge par les chemins d'exécution de l'hôte Script dédié (https://script.weegloo.com/v1), et ce chemin d'exécution unique accepte à la fois un jeton Weegloo User et un jeton de membre inscrit au produit (ServiceUser). ACMA n'a pas d'API Script, et les API de livraison en lecture seule (CDA, ACDA) non plus.

Un Script est une ressource dotée d'un version, et c'est une ressource facturable soumise à une limite de nombre par plan. Toutefois, contrairement à Content ou Media, il n'a pas de statut de publication. Son sys ne comporte pas de propriétés liées à la publication telles que status ou publish, et seul version augmente à chaque changement. Comme il n'existe pas de notion de publication ni de dépublication, la suppression se fait elle aussi immédiatement, sans dépublication préalable.

Structure de la ressource

Voici la réponse de lecture unitaire du Script « t6-http ». Avec sys (propriétés système), il possède comme propriétés de corps name, definition, ainsi que directCallEnabled et anonymousCallEnabled, qui ouvrent et ferment les chemins d'appel.

{
  "sys": {
    "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK",
    "type": "Script",
    "space": { "sys": { "id": "6jSUUAWT", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-07-15T12:35:47.575Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-07-15T12:35:47.575Z",
    "version": 1
  },
  "name": "t6-http",
  "directCallEnabled": true,
  "anonymousCallEnabled": false,
  "definition": {
    "method": "Post",
    "statements": [
      {
        "name": "resp",
        "method": "POST",
        "url": "https://postman-echo.com/post",
        "headers": [ { "key": "Content-Type", "value": "application/json", "secret": false } ],
        "body": { "prompt": "{ /payload/prompt }" },
        "timeoutMs": 10000,
        "retry": 0,
        "type": "Http"
      },
      {
        "value": { "status": "{ /resp/status }", "prompt": "{ /resp/body/json/prompt }" },
        "isError": false,
        "statusCode": 200,
        "type": "Return"
      }
    ]
  }
}

Propriétés principales :

• sys.id : identifiant unique du Script. Il s'insère dans le {scriptId} des chemins de lecture unitaire, de modification, de suppression et d'exécution.
• name : nom du Script (1 à 64 caractères). Utilisé dans la liste à l'écran et pour l'identification lors de la gestion.
• definition : le ScriptDefinition qui déclare ce que fait ce Script. Il se compose de la méthode d'appel (method), du tableau de statements (statements) et d'un schéma de payload facultatif (payloadSchema). Sa structure détaillée est traitée plus bas dans Définition et nom et dans la structure de niveau supérieur dans Script.
• directCallEnabled : indique si ce Script peut être appelé directement via /execute (booléen, true si omis). Si false, l'appel direct est refusé. Les autres chemins qui exécutent ce Script restent inchangés : l'action de liaison (script) d'un Webhook et un Scheduler ne passent pas par cet endpoint et l'exécutent donc tel quel.
• anonymousCallEnabled : indique si ce Script peut être appelé sans authentification via /execute/anonymous (booléen, false si omis). Une fois activé, même un tiers incapable de transporter un jeton peut exécuter ce Script par ce chemin, et l'exécution se fait sous l'identité de l'auteur. Les conditions et les règles d'enregistrement sont traitées plus bas dans Appel anonyme.

Notez que sys n'a ni status, ni publish, ni archive. Un Script n'est pas une ressource publiée sur un chemin de livraison ; c'est une ressource que l'on écrit et exécute via les API de gestion.

Propriétés système (sys)

Chaque Script porte des propriétés système communes dans l'objet sys. space, createdBy et updatedBy ont la forme Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Le status (statut de publication) et le publish (historique de publication) présents dans le sys de Content, Content Type et Media ne figurent pas sur un Script, car un Script n'est pas publié. Il n'a pas non plus de propriété archive. Ainsi, le version d'un Script augmente purement au rythme du nombre de créations et de modifications, sans aucune publication.

Définition et nom (name, definition)

Un Script a quatre propriétés de corps : name, definition, directCallEnabled et anonymousCallEnabled.

Clés de definition (ScriptDefinition) :

Les types et les champs de chaque statement que l'on place dans le tableau statements sont traités dans le Catalogue des statements, et les expressions { /pointer } qui font circuler les valeurs sont traitées dans les Expressions de valeur.

Dans l'exemple « t6-http » ci-dessus, le definition a method valant Post ; il appelle une API externe avec un statement Http, puis en renvoie le résultat avec un statement Return. Un statement qui comporte un appel externe, comme Http, déclare le temps qui lui revient, et ce temps s'ajoute au temps alloué à une exécution (voir Le temps alloué à une exécution).

Contraintes

Les contraintes statiques ci-dessus sont vérifiées au moment de l'enregistrement (création/modification), et une violation entraîne le rejet de l'enregistrement. Le nombre d'appels externes et le nombre total de statements ne sont pas des erreurs de validation mais des limites de plan : une même définition est donc admise sur un plan supérieur.

Lors de l'enregistrement, les permissions et le type de ressource sont vérifiés eux aussi.

• On vérifie si l'auteur détient réellement les permissions de ressource et d'action qu'utilisent ces statements (s'il en manque une seule, l'enregistrement est refusé ; voir Erreurs). Pour les statements qui lisent un membre (ServiceUser), la vérification ne porte pas sur les mappages de permissions mais sur le SETTING_SERVICE_LOGIN du settings du SpaceRole.
• Si la définition contient un statement qui modifie un membre (ServiceUser), l'enregistrement est refusé. Cette ressource étant uniquement lisible depuis un Script, aucun rôle ne permet un tel enregistrement.

Les règles détaillées, le budget de temps et les limites de longueur des valeurs vérifiées pendant l'exécution sont traités dans Sémantique d'exécution, contraintes et sécurité.

Un Script est une ressource facturable et le nombre par Organization est limité selon le plan (Free 10 / Basic 30 / Pro 100 / Enterprise illimité). Une fois la limite atteinte, la création d'un nouveau Script est refusée (voir les limites de nombre par plan).

Appel anonyme (anonymousCallEnabled)

Si l'on met anonymousCallEnabled à true, ce Script s'exécute aussi par un chemin dédié sans authentification.

{method} https://script.weegloo.com/v1/spaces/{spaceId}/scripts/{scriptId}/execute/anonymous

Le besoin est rare. C'est un dispositif destiné aux tiers qui doivent nous envoyer un callback mais ne prennent pas en charge les en-têtes personnalisés et n'ont donc aucun moyen de transporter un Access Token, comme les prestataires de paiement (PG, MoR). Tout appelant capable de transporter un jeton utilise le chemin authentifié (/execute).

• Le chemin authentifié reste inchangé. /execute exige toujours un jeton Bearer et la permission Execute de Script. Le seul chemin qui devient non authentifié est /execute/anonymous.
• Il n'accepte pas de jeton. Même transmis, un jeton est ignoré et l'exécution se fait toujours sous l'identité de l'auteur. Pour exécuter sous l'identité de l'appelant, on utilise /execute.
• Il faut franchir les deux barrières. Si anonymousCallEnabled vaut false, l'appel est refusé comme un accès non authentifié ; si directCallEnabled vaut false, il est refusé parce que l'appel direct est fermé. Le code renvoyé diffère selon la barrière rencontrée (voir Erreurs). L'autorisation de l'anonyme étant examinée en premier, un appelant sans qualification ne peut pas découvrir l'état de configuration de ce Script.
• La suite est identique à /execute. La méthode HTTP de la requête doit correspondre à definition.method, et l'appel consomme le quota d'exécution de Script de l'Organization et est compté dans l'usage.
• Ce chemin se trouve sur le même hôte Script (https://script.weegloo.com/v1) que le chemin d'exécution authentifié.

L'exécution se fait sous l'identité de l'auteur

Faute d'appelant, l'exécution se fait sous l'identité de l'utilisateur qui a créé ce Script (sys.createdBy).

• Le createdBy et le updatedBy des Content et Media créés ou modifiés dans le Script reçoivent l'auteur (et non l'appelant anonyme : il n'existe aucune autre identité à qui les attribuer).
• Le createdBy: ":self" de where se résout lui aussi sur l'auteur et non sur l'appelant. Activer l'anonyme en laissant tel quel un filtre de propriété écrit en supposant un appelant authentifié ouvrirait silencieusement les ressources de l'auteur : une telle définition est donc refusée à l'enregistrement (voir ci-dessous).

Vérifications supplémentaires à l'enregistrement

Un Script dont anonymousCallEnabled vaut true est soumis à une règle de plus.

C'est qu'un appel anonyme n'a pas d'identité d'appelant et que :self se résout sur l'auteur. L'enregistrement empêche ainsi qu'un filtre de propriété écrit en supposant un appelant authentifié soit silencieusement contourné.

L'authentification effective, c'est le Script qui l'assure

Ce chemin n'a aucune authentification posée par la plateforme. Quiconque connaît l'URL peut l'appeler, et cet appel consomme le quota d'exécution de Script de l'Organization sans limitation de débit distincte. Un Script anonyme doit donc vérifier lui-même les requêtes qu'il reçoit.

• On place tout au début un Signature pour vérifier la signature portant sur { /rawPayload } et, en cas d'échec, on coupe sur place avec Return. Un exemple complet figure dans la vérification de signature de webhook du cookbook.
• Vérifier aussi la fenêtre de rejeu (replay window) avec /now empêche de renvoyer une requête passée (voir /now).
• Un Script anonyme ne contient que ce que ce callback doit réellement faire. Un Script s'exécutant avec les permissions déléguées de l'auteur, tout ce qu'il contient est ouvert sans authentification (voir Modèle de sécurité).

ScriptLog

Chaque fois qu'un Script s'exécute, un enregistrement est conservé. Cet enregistrement est le ScriptLog. Il est en lecture seule et n'a pas d'endpoint de création, de modification ni de suppression. Son chemin est /spaces/{spaceId}/scripts/{scriptId}/logs, et son URL de base n'est pas l'hôte d'exécution mais celle de CMA, https://cma.weegloo.com/v1. Sa lecture exige la permission Read sur ce Script.

{
  "sys": {
    "id": "3trmXRM7pLdV5Rz8kWq2NcHfJt4bYs",
    "type": "ScriptLog",
    "space": { "sys": { "id": "6jSUUAWT", "type": "Refer", "targetType": "Space" } },
    "script": { "sys": { "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK", "type": "Refer", "targetType": "Script" } },
    "trigger": { "sys": { "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK", "type": "Refer", "targetType": "Script" } },
    "requestId": "3trmXRM9wTbK4Vz7hLp2QsNdRf6cYm",
    "returned": true,
    "value": { "status": 200, "prompt": "Description produit d'une robe d'été, 3 lignes" },
    "success": true,
    "statusCode": 200,
    "durationMs": 195,
    "createdBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-07-15T12:41:03.902Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-07-15T12:41:03.902Z"
  }
}

Toutes les valeurs se trouvent dans sys et il n'y a pas de propriété de corps. Une clé sans valeur est absente de la réponse.

trigger désigne ce qui a déclenché cette exécution. Pour un appel direct, c'est le Script lui-même ; si l'exécution a eu lieu via l'action de liaison d'un Webhook, c'est ce Webhook ; et si c'est un Scheduler qui l'a lancée, c'est ce Scheduler.

requestId est la même valeur que le requestId de l'enveloppe de réponse d'exécution. Pour retrouver l'enregistrement d'une exécution à partir de la réponse reçue par l'appelant, on utilise cette valeur comme critère de recherche.

L'enregistrement est écrit une fois l'exécution terminée et ne change plus. Une exécution réussie disparaît au bout d'une heure, une exécution en échec au bout de trois jours. Les valeurs qu'il faut conserver plus longtemps, enregistrez-les comme Content depuis l'intérieur du Script.

createdBy désigne l'identité sous laquelle cette exécution a été effectuée. Une exécution appelée avec un jeton Weegloo User, c'est cet utilisateur ; une exécution appelée avec un jeton de membre (ServiceUser), c'est ce membre. Pour une exécution sans appelant, l'identité vient du déclencheur : une exécution anonyme, c'est l'auteur de ce Script ; une exécution lancée par un Scheduler, c'est l'utilisateur qui a créé ce Scheduler (il peut différer de l'auteur du Script) ; et une exécution effectuée par un Webhook, c'est l'utilisateur qui a créé ce Webhook. Le runAs d'un Webhook ne fait que décider au nom de qui les opérations à l'intérieur du Script sont effectuées ; il ne change pas l'attribution de ce journal.

Erreurs

Ce sont les codes qui surviennent lorsque l'on appelle ou que l'on supprime un Script. Les codes qui surviennent lors de l'enregistrement d'une définition figurent dans Erreurs de Sémantique d'exécution, contraintes et sécurité, les codes qui sanctionnent une infraction aux règles des expressions de valeur dans Erreurs des Expressions de valeur, et les codes communs à toutes les ressources dans Erreurs communes.

API

L'URL de base des cinq endpoints ci-dessous (liste, lecture, création, modification, suppression) est celle de CMA, https://cma.weegloo.com/v1, et un jeton Bearer authentifiant auprès de CMA est requis dans l'en-tête Authorization. La modification doit aussi envoyer l'en-tête X-Weegloo-Version (le sys.version actuel de la ressource) pour le contrôle de concurrence optimiste. Les deux lectures de ScriptLog tout en bas utilisent la même URL de base CMA.

L'URL de base des deux endpoints d'exécution est celle de l'hôte Script dédié, https://script.weegloo.com/v1. L'exécution authentifiée (/execute) accepte à la fois un jeton Bearer d'identité Weegloo User et un jeton Bearer d'identité membre (ServiceUser), et dans les deux cas l'appelant a besoin de la permission Execute sur ce Script.

Seule l'exécution anonyme (/execute/anonymous) fait exception et n'exige pas d'en-tête d'authentification. Elle se trouve sur le même hôte Script, et n'est atteignable que si ce Script a activé anonymousCallEnabled (voir Appel anonyme ci-dessus).

La réponse de l'exemple d'exécution authentifiée ci-dessus n'a pas de return, car le Script visé s'est terminé sans atteindre de Return porteur d'une valeur (auquel cas statusCode vaut la valeur par défaut 200). Lorsqu'un Return renvoie une valeur, comme dans l'exemple d'exécution anonyme, la réponse contient return (ou error si Return.isError vaut vrai). L'ensemble des règles de la réponse est traité dans la section Requête et réponse de l'Aperçu de Script.

Documents liés

• Aperçu de Script : traite la structure ScriptDefinition de niveau supérieur, la requête et la réponse, ainsi que le temps alloué à une exécution.
• Catalogue des statements : traite les champs et les résultats de chaque statement que l'on place dans statements.
• Expressions de valeur : traite les références { /pointer } et les opérations JsonLogic.
• Sémantique d'exécution, contraintes et sécurité : traite les contraintes statiques, les limites de nombre par plan, ainsi que le modèle de permissions et de sécurité.
• SpaceRole et ServiceUserRole : traitent la manière d'accorder à un rôle les permissions d'action d'un Script (Execute compris).