Script

Imagine que gestiona la tienda en línea de una tienda de ropa. Cada vez que sube un producto, escribir a mano una descripción detallada atractiva para cada uno resulta engorroso. Por eso le gustaría que, con solo introducir el nombre del producto y unas palabras clave, una IA redacte la descripción detallada en su lugar. Pero para llamar a ese servicio de redacción con IA hace falta una llave secreta (access token, la llave con la que el servicio externo comprueba "si de verdad se trata de un usuario que ha pagado"). Si coloca esta llave en el sitio web que ve el cliente (el navegador), cualquiera puede extraerla y acaba filtrándose. Con una llave filtrada, otra persona podría usar este servicio a su antojo y hacer que a usted le cobren.

Por eso hace falta algo que, manteniendo la llave escondida donde el cliente no la vea, llame a la IA en lugar del sitio web y rellene el producto con ese resultado. Ese algo es el Script. Un Script consiste en dejar anotadas en orden las tareas que hay que hacer, como "llama a la IA con esta llave y rellena la descripción detallada de este producto con el texto recibido". No se anota con código, sino con un formato fijo (JSON, una forma de anotar datos que escribe los elementos y los valores entre llaves). Al sitio web le basta con llamar a este Script por internet, y la llave queda oculta dentro del Script, sin que el cliente la vea.

Se puede comparar con dejar colgada en la cocina una receta escrita de antemano. Cuando un cliente pide ese plato (cuando el sitio web llama al Script), la cocina (WEEGLOO) lo prepara siguiendo el orden anotado en la receta y sirve el plato terminado. El dueño solo ha escrito y colgado la receta; no cocina en persona cada vez que entra un pedido. En esta página veremos qué es un Script y qué forma tiene, y qué devuelve cuando se le llama; después comprobaremos esa forma con el ejemplo del Script de "Rellenar la descripción del producto" de la tienda de ropa. Al final veremos también cómo enlazar este Script para que se ejecute solo cuando se da de alta un producto.

El trabajo que hace un Script en su lugar

Incluso para rellenar una sola descripción de producto, por detrás hay que hacer varias cosas. Comprobar si quien llama tiene permiso, revisar si los valores enviados son correctos, llamar al servicio de IA externo con la llave escondida, colocar el resultado recibido en el lugar deseado (la descripción detallada del producto) y devolver una respuesta. Antes había que crear uno mismo el programa intermedio que hacía estas tareas, subirlo a un servidor y mantenerlo. El objetivo del Script es asumir estas tareas dejándolas anotadas todas en un solo lugar, sin código.

• Un Script es una única ventanilla de llamada. Cada ventanilla que el sitio web puede llamar por internet es un Script. Con la forma que se usa al llamar (method) se determina qué Script se ejecuta.
• Las tareas se disponen de arriba abajo. Dentro de un Script se anotan en orden las operaciones que se van a ejecutar. Se ejecutan una tras otra desde arriba, y cada operación hereda el resultado de la anterior.
• Se eligen y combinan operaciones predefinidas. No se introduce código cualquiera, sino que se eligen y disponen operaciones ya preparadas (crear, leer, modificar o eliminar recursos, llamar a servicios externos, guardar valores, comprobar condiciones, repetir, etc.).

La definición donde se anota qué hacer

Un Script se compone de una "definición" que fija cuatro cosas.

• La forma de llamada (method): es la forma que se usa al llamar a este Script. Es uno de Get, Post, Put, Patch o Delete, y al llamar, con este valor se determina de qué Script se trata.
• El lugar de ejecución (executionMode): indica si se ejecuta de inmediato en el mismo punto de la llamada (Sync) o en segundo plano (Async). Se trata más abajo, en Ejecución inmediata y ejecución en segundo plano.
• Las tareas (statements): es la lista de operaciones que se ejecutan de arriba abajo. Debe haber al menos una.
• La comprobación de la entrada (payloadSchema, opcional): es el formato con el que se verifica, antes de ejecutar, la entrada que se envía junto con la llamada. Si se define, la entrada que no se ajusta al formato no se ejecuta y se devuelve.

Veamos como ejemplo el Script de "Rellenar la descripción del producto" de la tienda de ropa. Lo que este Script maneja es un producto que contiene el nombre del producto y unas palabras clave. La entrada que se pasa desde el sitio web (en la ejecución automática que veremos más adelante, se transmite tal cual el producto dado de alta) tiene esta forma.

{
  "sys": { "id": "3trmXRMKq7bd0Prbef1... (número de producto)" },
  "fields": {
    "productName": { "es-ES": "Termo de acero inoxidable 500 ml" },
    "keywords":    { "es-ES": "aislamiento térmico, ligereza, camping" }
  }
}

Esta es la definición del Script que recibe este producto, crea una descripción detallada con una IA externa y rellena la descripción detallada (body) de ese producto.

{
  "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 secreto>", "secret": true }
      ],
      "body": {
        "product":  "{ /payload/fields/productName/es-ES }",
        "keywords": "{ /payload/fields/keywords/es-ES }"
      },
      "name": "gen" },
 
    { "type": "ResourcePatch", "resource": "Content",
      "target": { "sys": { "id": "{ /payload/sys/id }" } },
      "fields": { "body": { "es-ES": "{ /gen/body/text }" } },
      "publish": true },
 
    { "type": "Return", "value": { "id": "{ /payload/sys/id }" }, "statusCode": 200 }
  ]
}

• La primera operación (Http) llama al servicio de IA externo con la llave escondida. Si en la cabecera que contiene la llave se añade secret: true, ese valor no queda a la vista del cliente y solo se revela justo antes de la llamada. El resultado recibido se guarda en un nombre llamado gen.
• La segunda operación (ResourcePatch) rellena solo la descripción detallada (body) de ese producto con el texto recibido antes ({ /gen/body/text }). No toca el resto de los valores del producto.
• Se usa el marcador de posición { /… }, que hace fluir un valor hacia el siguiente paso. { /payload/fields/productName/es-ES } señala el nombre del producto recibido, { /payload/sys/id } señala el número de ese producto, y { /gen/body/text } señala el texto que ha devuelto la IA.
• La última operación (Return) devuelve el número del producto cuya descripción se ha rellenado.
• Por qué los valores de un Content se anotan por idioma, como en { "es-ES": … }, todos los tipos de operación que se pueden incluir en statements, y la sintaxis de los marcadores de posición y de las condiciones y cálculos se tratan en Expresiones de valor y el Catálogo de statements.

Qué devuelve cuando se le llama

Al final, el Script devuelve a quien lo ha llamado el valor de la operación Return. La respuesta que se devuelve contiene lo siguiente.

• requestId: es el número de identificación que señala esta ejecución.
• durationMs: es el tiempo que ha tardado la ejecución (en milisegundos).
• statusCode: es el código de estado del Return alcanzado (200 si no se define aparte).
• return o error: es el valor que ha devuelto Return. Normalmente va en return, y si ese valor se marca como error, va en error. Los dos no aparecen juntos.

Ahora bien, "Rellenar la descripción del producto" llama a una IA externa, así que se ejecuta en segundo plano (véase más abajo Ejecución inmediata y ejecución en segundo plano). Por eso, al llamarlo, primero vuelven de inmediato solo 202 y requestId con el sentido de "recibido", y la respuesta anterior se obtiene un poco después volviendo a preguntar con ese requestId (sondeando). La respuesta ya terminada tiene esta forma.

{
  "requestId": "3trmXRMZ8kqLb2Prdf1eYc0axWnKv",
  "durationMs": 1840,
  "statusCode": 200,
  "return": { "id": "3trmXRMKq7bd0Prbef1... (número de producto)" }
}

Con el id de este return, el sitio web puede señalar el producto cuya descripción se acaba de rellenar y mostrar al cliente la nueva descripción detallada.

Si el Script termina sin llegar a un Return, vuelve solo con statusCode 200, sin return ni error. Las reglas detalladas para fijar con Return el cuerpo de la respuesta y el código de estado se tratan en el Return del Catálogo de statements.

Ejecución inmediata y ejecución en segundo plano

Un Script se puede ejecutar de dos formas, y se fija con el executionMode de la definición.

• Ejecución inmediata (Sync): se ejecuta al momento en el mismo punto de la llamada y devuelve enseguida la respuesta completa. Es adecuada para tareas que terminan rápido sin llamadas externas.
• Ejecución en segundo plano (Async): se ejecuta por detrás. Al llamar, primero devuelve de inmediato solo 202 y requestId con el sentido de "recibido", y el resultado real se obtiene más tarde volviendo a preguntar con ese requestId (sondeando).

Hay una regla. Si contiene aunque sea una sola operación que llama a un servicio externo o que recibe un archivo y lo incorpora como Media, ese Script debe ejecutarse obligatoriamente en segundo plano. "Rellenar la descripción del producto" también llama a una IA externa, así que es de ejecución en segundo plano. Si intenta guardarlo como ejecución inmediata, se devuelve al guardarlo. Es para no retener a quien llama aunque la respuesta externa tarde.

El tiempo disponible para la ejecución también tiene un presupuesto. La ejecución inmediata es de 10 segundos por defecto, y la ejecución en segundo plano de 60 segundos por defecto. Las reglas detalladas, como la forma de sondear y qué operaciones obligan a la ejecución en segundo plano, se tratan en Semántica de ejecución, restricciones y seguridad.

Quién crea un Script

En lugar de que una persona escriba a mano, una por una, operaciones complejas, el Script está diseñado para que lo cree un agente de IA o un programa. Si le pide de palabra a un agente de IA "crea una ventanilla que rellene la descripción de los productos", el agente crea en su lugar una definición como la que hemos visto arriba. Con una sola frase surge una ventanilla que trabajará por detrás del sitio web.

El flujo detallado para crear un Script con un agente de IA se trata en Crear un backend con solo decírselo a la IA.

Una persona ve y gestiona el Script creado desde la pantalla de administración (el estudio de contenidos). Comprueba el nombre y la definición y, si hace falta, lo modifica o lo elimina. Quien llama realmente al Script es el sitio web o la app que ve el cliente (el frontend). Con la identidad de un miembro que se ha registrado en el producto (ServiceUser) solo se puede ejecutar el Script, pero no crearlo ni modificarlo.

En qué se diferencia del Webhook

Script y Webhook son ambos dispositivos que conectan con el exterior, pero la dirección de la llamada es opuesta.

• El Webhook reacciona por sí solo cuando ocurre un cambio fijado (como que se dé de alta un producto). Aunque nadie lo llame, si ocurre el suceso, se pone en marcha por sí solo. Ahora bien, no devuelve ningún resultado de vuelta.
• El Script es una ventanilla que el sitio web llama directamente cuando lo necesita. Solo se ejecuta si se le llama, y el resultado de esa ejecución se recibe de vuelta al momento o, si es de ejecución en segundo plano, mediante sondeo.

"Cuando el dueño pulsa 'Rellenar descripción', se llama a la IA y se recibe y rellena la descripción detallada" es una tarea en la que quien llama espera el resultado, así que le conviene un Script; "cuando se da de alta un producto, ocurre algo automáticamente" es una tarea que reacciona a un suceso, así que le conviene un Webhook. Y ambos se pueden usar juntos. Lo veremos justo a continuación.

Que la descripción se rellene sola al dar de alta el producto

Hasta ahora, el dueño llamaba al Script directamente pulsando el botón "Rellenar descripción". Un paso más allá, puede hacer que el Script se ejecute por sí solo en el instante en que se da de alta un producto, sin pulsar ningún botón. Esto es porque el Webhook capta ese suceso y llama en su lugar a nuestro Script.

El flujo es el siguiente.

1. El dueño da de alta un producto. En ese momento rellena solo el nombre del producto y las palabras clave, y deja vacía la descripción detallada.
2. El Webhook detecta el suceso de que se da de alta un nuevo producto.
3. El Webhook pasa tal cual el producto recién dado de alta a nuestro Script de "Rellenar la descripción del producto" y lo ejecuta.
4. El Script crea la descripción detallada con una IA externa y rellena la descripción detallada (body) de ese producto.
5. Poco después, la descripción detallada del producto ya aparece rellenada por sí sola.

Aquí el Script es exactamente el mismo que antes. Lo único que cambia es el motivo por el que se le llama. En lugar del botón, quien lo llama es el suceso "se ha dado de alta un producto". Como el producto dado de alta se convierte tal cual en la entrada del Script, este toma ese producto con { /payload/sys/id } y rellena la descripción detallada.

En el lado del Webhook hay tres cosas que definir: ante qué suceso reaccionar (cuando se da de alta un nuevo producto), a qué productos reaccionar solamente (limitándolo por tipo de producto) y qué hacer (llamar a nuestro Script en lugar de avisar a una dirección externa).

Podría preocuparle que la descripción detallada que rellena el Script vuelva a provocar el suceso "el producto ha cambiado" y se repita sin fin. No es así. La escritura del Script no provoca nuevos sucesos a menos que se active aparte, y la plataforma también impide la repetición sin fin.

La configuración detallada para enlazarlo de esta forma se trata en Webhook.

Cuándo resulta especialmente útil un Script

Si la tarea consiste únicamente en avisar al exterior de que "ha ocurrido esto", basta con un solo Webhook. Pero si, tras llamar a un servicio externo, hay que ver ese resultado y luego decidir y actuar, hace falta un Script que reúna todo ese flujo en un solo lugar.

Tomemos como ejemplo una función de pago que crea imágenes con IA. Cuando un cliente solicita la creación de una imagen, debe ocurrir en orden lo siguiente.

1. Se comprueba si el cliente tiene créditos suficientes. Si no le alcanzan, se detiene aquí y se le avisa: "No tiene créditos suficientes".
2. Si son suficientes, se descuentan primero los créditos correspondientes al coste.
3. Se llama al servicio externo de IA y se crea la imagen.
4. La imagen creada se guarda como un Content.
5. Si surge algún problema en el paso 3 o el 4, se devuelven los créditos que se acaban de descontar.

Un Webhook puede avisar al exterior de que "ha entrado una solicitud", pero no puede, a partir del resultado, descontar créditos ni revertir en caso de fallo, como se hace aquí. Encadenar varios pasos según las condiciones y, si algo falla, revertir los pasos anteriores es tarea del Script. Los casos en los que un Script resulta especialmente valioso son los siguientes.

• Cuando hay que ver el resultado y actuar en consecuencia: según la respuesta que devuelve el servicio externo, se decide en el acto si guardar, descontar o revertir.
• Cuando no debe haber conflictos aunque lleguen a la vez: aunque un mismo cliente haga dos solicitudes en un intervalo corto, los créditos no deben descontarse dos veces. El Script, tras leer el valor y justo antes de guardarlo, comprueba mediante la versión "si otra solicitud no ha cambiado este valor mientras tanto" y, si hay conflicto, se detiene.
• Cuando hace falta un permiso que quien llama no tiene: el cliente no tiene permiso para modificar por sí mismo el saldo de créditos. Aun así, el descuento se produce de forma segura porque el Script se ejecuta con el permiso delegado de quien lo creó. A quien llama solo hay que darle permiso para ejecutar el Script. Esta delegación se trata en detalle más abajo, en Permisos para ejecutar y gestionar.

La forma de escribir este ejemplo como una definición real de Script se trata en el ejemplo de comprobar, descontar y devolver créditos del Cookbook (Ejemplos prácticos).

Permisos para ejecutar y gestionar

Para ejecutar o gestionar un Script, el rol (SpaceRole) debe tener el permiso correspondiente.

• Ejecución: para llamar a un Script, el rol debe tener el permiso de ejecución de Script (Execute). Sin él, la ejecución queda bloqueada.
• Gestión: para crear, modificar y eliminar un Script se necesitan, respectivamente, los permisos de creación, modificación y eliminación.

Al ejecutar un Script, lo único que se comprueba es si quien llama tiene el permiso de ejecución (Execute). Las operaciones individuales dispuestas dentro del Script no se comprueban una a una en cuanto al permiso en el momento de ejecutarlas. Es como cuando se llama a un programa cuya ejecución está permitida: solo se mira el permiso para ejecutar ese programa, y no se pide autorización cada vez para cada una de las cosas que hace dentro.

En cambio, el permiso de cada operación se comprueba de antemano no al ejecutar, sino al guardar el Script. Solo se guarda si quien lo crea posee realmente el permiso para las operaciones sobre Content y Media que manejan las operaciones dentro de ese Script. Por ejemplo, el Script de "Rellenar la descripción del producto" modifica la descripción detallada del Content de producto, así que si quien lo crea no tiene permiso para modificar el producto, el guardado se devuelve. Un Script que contiene una operación sin permiso no se guarda desde el principio.

Visto así, ejecutar un Script equivale a llevarlo a cabo en su lugar con el permiso delegado de quien lo creó. Aunque sea una operación que quien llama no posee por sí mismo, si es una operación que quien lo creó puede hacer, a través del Script ocurre tal cual. Por eso, al crear un Script hay que decidir con cuidado qué operaciones se incluyen dentro. El permiso de quien lo creó es, precisamente, el alcance de lo que ese Script puede hacer.

Cómo se asignan los permisos a un rol se trata en Roles y permisos.

Cosas que conviene saber

• No hay publicación. El Script no es un tipo de recurso que se publique para entregarlo a los visitantes, sino una ventanilla que se crea en la pantalla de administración y que el sitio web llama y usa. Por eso, a diferencia de Content y Media, no tiene estados de publicación ni de anulación de publicación, y en cuanto se crea ya se puede usar. Cada vez que se modifica solo sube una versión, y al eliminarlo también se elimina de inmediato, sin un paso previo como la anulación de publicación.
• Hay un límite de cantidad. El Script es un elemento facturable, así que la cantidad que puede tener una sola Organization está fijada según el plan (Free 3, Basic 10, Pro 50, Enterprise ilimitado). Al alcanzar el límite no se pueden crear nuevos Script, y si elimina un Script que no usa, vuelve a quedar un hueco libre.

Gestionar en el estudio de contenidos

El Script creado se ve y se gestiona en la pantalla de Script del estudio de contenidos. Al pulsar Script en el menú de la izquierda, aparece una lista de los Script creados hasta ahora. En cada fila se ven el nombre, la forma de llamada (Método HTTP), el Script ID que señala al Script, el lugar de ejecución (Modo de ejecución) y la fecha de la última modificación.

La definición suele crearla en su lugar un agente de IA, pero también puede crearla usted mismo en esta pantalla. Un nuevo Script se crea con el botón Crear de la parte superior derecha de la lista.

1. Pulse el botón Crear de la parte superior derecha de la lista.
2. Escriba Rellenar la descripción del producto en el campo Nombre.
3. Elija Método HTTP como la forma de llamar a este Script (aquí, POST).
4. Elija Modo de ejecución como Async (ejecución en segundo plano). Como este Script llama a una IA externa, debe ejecutarse obligatoriamente en segundo plano.
5. Introduzca en el campo Statement la definición con las tareas anotadas. Puede introducir tal cual la definición del ejemplo de "Rellenar la descripción del producto" de arriba.

Si quiere comprobar antes de ejecutar la entrada que se enviará junto con la llamada, active Validación de Payload en Payload Schema y deje escrito el formato que se va a comprobar. Cuando lo haya rellenado todo, pulse el botón Guardar de la parte superior derecha.

Al pulsar un Script en la lista se abre la pantalla de detalle. Aquí puede comprobar el nombre y la definición, y también ver la dirección con la que se llama a este Script (la Execute URL). Tras modificar la definición, al pulsar Guardar sube una versión, y los Script que ya no usa se eliminan con Eliminar.

Qué hacer a continuación

• Descripción general de Script: trata la estructura de nivel superior de la definición que forma un Script, las reglas de ejecución y el conjunto de documentos de sintaxis.
• Catálogo de statements: trata los tipos y los campos de las operaciones que se pueden incluir en statements (crear, leer, modificar o eliminar recursos, llamar a servicios externos, condiciones, bucles, etc.).
• Webhook: trata cómo hacer que algo reaccione automáticamente cuando ocurre un cambio fijado, igual que se enlaza un Script para que se ejecute solo cuando se da de alta un producto.