Weegloo Docs - Script

Imagine que você administra uma loja de roupas online. Escrever, uma por uma, uma descrição detalhada atraente para cada produto que você publica dá trabalho. Por isso, você quer que baste informar o nome do produto e algumas palavras-chave para uma IA escrever a descrição detalhada no seu lugar. Só que, para chamar esse serviço de escrita por IA, é preciso ter uma chave secreta (access token, a chave com que o serviço externo confere se "você é mesmo um usuário que pagou pelo uso"). Se você guardar essa chave no site que o cliente vê (no navegador), qualquer pessoa consegue retirá-la de lá, e ela acaba vazando. Com a chave vazada, outra pessoa pode usar esse serviço à vontade e gerar cobranças para você.

Por isso, você precisa de algo que mantenha a chave escondida, fora do alcance dos olhos do cliente, e que, no lugar do site, chame a IA e preencha o resultado no produto. O Script é isso. O Script é um registro, em ordem, das tarefas a fazer, como "chame a IA com esta chave e preencha, na descrição detalhada deste produto, o texto recebido". Ele é escrito não em código, mas em um formato definido (JSON, uma forma de anotar dados com itens e valores escritos entre chaves). O site só precisa chamar este Script pela internet, e a chave, escondida dentro do Script, não fica visível para o cliente.

Dá para comparar com uma receita escrita de antemão e pendurada na cozinha. Quando o cliente pede aquele prato (quando o site chama o Script), a cozinha (o WEEGLOO) prepara na ordem escrita na receita e serve o prato pronto. O dono apenas escreveu e pendurou a receita; ele não cozinha pessoalmente cada vez que chega um pedido. Nesta página, primeiro vamos ver o que é o Script, como ele é e o que ele devolve quando é chamado, e depois confirmar esse formato usando como exemplo o Script de "Preencher descrição do produto" da loja de roupas. No final, também veremos como ligar este Script para que ele seja executado automaticamente quando um produto é cadastrado.

O que o Script faz no seu lugar

Mesmo para preencher uma única descrição de produto, há várias tarefas a fazer nos bastidores. É preciso conferir se quem chama tem permissão, verificar se os valores enviados estão corretos, chamar o serviço externo de IA com a chave escondida, colocar o resultado recebido no lugar desejado (a descrição detalhada do produto) e devolver a resposta. Antigamente, era preciso criar por conta própria o programa intermediário que faz essas coisas, colocá-lo em um servidor e mantê-lo. O objetivo do Script é fazer todas essas coisas no seu lugar, anotando-as em um só lugar, sem código.

Um Script é um único ponto de chamada. Cada ponto que o site pode chamar pela internet corresponde a um Script. É pela forma usada na chamada (method) que se determina qual Script será executado.
As tarefas ficam dispostas de cima para baixo. Dentro do Script, você anota as ações a executar em ordem. Elas são executadas em sequência, de cima para baixo, e cada ação recebe o resultado da ação anterior.
Você escolhe e combina ações predefinidas. Em vez de inserir qualquer código, você escolhe e dispõe ações já preparadas de antemão (criar, ler, alterar e excluir recursos, chamar serviços externos, guardar valores, verificar condições, repetir, entre outras).

A definição onde você anota o que fazer

Um Script é formado por uma "definição" que fixa quatro coisas.

A forma de chamar (method): a forma usada para chamar este Script. É um entre Get, Post, Put, Patch e Delete, e é por esse valor, na chamada, que se determina de qual Script se trata.
O local de execução (executionMode): se o Script é executado na hora, no lugar em que foi chamado (Sync), ou executado em segundo plano (Async). Isso é tratado adiante em Execução imediata e execução em segundo plano.
As tarefas (statements): a lista de ações a executar de cima para baixo. Precisa ter pelo menos uma.
A verificação da entrada (payloadSchema, opcional): o formato para conferir, antes da execução, a entrada enviada junto com a chamada. Se você o definir, uma entrada que não corresponde ao formato é recusada, sem ser executada.

Vamos ver como exemplo o Script de "Preencher descrição do produto" da loja de roupas. O que este Script trata é um único produto que contém o nome do produto e palavras-chave. A entrada que o site passa (na execução automática que veremos adiante, o produto cadastrado é passado tal e qual) tem este formato.

{
  "sys": { "id": "3trmXRMKq7bd0Prbef1... (número do produto)" },
  "fields": {
    "productName": { "pt-BR": "Copo térmico de aço inox 500ml" },
    "keywords":    { "pt-BR": "isolamento térmico, leve, camping" }
  }
}

Esta é a definição de um Script que recebe esse produto, gera a descrição detalhada com a IA externa e preenche a descrição detalhada (body) desse produto.

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

A primeira ação (Http) chama o serviço externo de IA com a chave escondida. Se você marcar com secret: true o cabeçalho que carrega a chave, esse valor não fica visível para o cliente e só é revelado no instante anterior à chamada. O resultado recebido é guardado sob o nome gen.
A segunda ação (ResourcePatch) preenche apenas a descrição detalhada (body) desse produto com o texto recebido antes ({ /gen/body/text }). Os demais valores do produto não são tocados.
Usa-se o marcador de posição { /… }, que faz um valor fluir para a etapa seguinte. { /payload/fields/productName/pt-BR } aponta o nome do produto recebido, { /payload/sys/id } aponta o número desse produto e { /gen/body/text } aponta o texto que a IA devolveu.
A última ação (Return) devolve o número do produto cuja descrição foi preenchida.
O motivo de anotar o valor de um Content por idioma, como em { "pt-BR": … }, os tipos completos de ações que você pode colocar em statements e a sintaxe de marcadores, condições e cálculos são tratados em Expressões de valor e no Catálogo de Statement.

O que ele devolve quando é chamado

No final, o Script devolve a quem o chamou o valor da ação Return. A resposta devolvida contém o seguinte.

requestId: o número de identificação que aponta esta execução.
durationMs: o tempo que a execução levou (em milissegundos).
statusCode: o código de status do Return alcançado (200 se você não definir outro).
return ou error: o valor devolvido pelo Return. Normalmente ele vai em return; se você marcar esse valor como erro, ele vai em error. Os dois não aparecem juntos.

Só que o Script "Preencher descrição do produto" chama a IA externa, então ele é executado em segundo plano (veja abaixo Execução imediata e execução em segundo plano). Por isso, ao ser chamado, ele primeiro devolve de imediato apenas o 202 e o requestId, com o sentido de "recebido", e a resposta acima é obtida um instante depois, consultando de novo (fazendo polling) com esse requestId. A resposta já concluída tem este formato.

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

Com o id desse return, o site pode identificar o produto cuja descrição acabou de ser preenchida e mostrar ao cliente a nova descrição detalhada.

Se o Script terminar sem chegar a um Return, ele volta apenas com statusCode 200, sem return nem error. As regras detalhadas para definir o corpo da resposta e o código de status com o Return são tratadas em Return no Catálogo de Statement.

Execução imediata e execução em segundo plano

O Script pode ser executado de duas formas, e você define isso pelo executionMode da definição.

Execução imediata (Sync): executa na hora, no lugar em que foi chamado, e devolve a resposta pronta de imediato. É adequada para tarefas que terminam rápido, sem chamadas externas.
Execução em segundo plano (Async): executa nos bastidores. Ao ser chamado, ele primeiro devolve de imediato apenas o 202 e o requestId, com o sentido de "recebido", e o resultado real é obtido depois, consultando de novo (fazendo polling) com esse requestId.

Há uma regra. Se houver pelo menos uma ação que chama um serviço externo ou que recebe um arquivo e o traz para dentro como Media, esse Script precisa obrigatoriamente ser de execução em segundo plano. O Script "Preencher descrição do produto" também chama a IA externa, então é de execução em segundo plano. Se você tentar salvá-lo como execução imediata, ele é recusado no momento de salvar. Isso serve para que uma resposta externa demorada não prenda quem fez a chamada.

O tempo disponível para a execução também tem um limite. A execução imediata é de 10 segundos por padrão, e a execução em segundo plano, de 60 segundos por padrão. As regras detalhadas, como a forma de fazer polling e quais ações exigem a execução em segundo plano, são tratadas em Semântica de execução, limites e segurança.

Quem cria o Script

Em vez de uma pessoa anotar à mão, uma a uma, ações complexas, o Script foi projetado para ser criado por um agente de IA ou por um programa. Se você pedir ao agente de IA, em palavras, "crie um ponto de chamada que preencha a descrição do produto", o agente cria no seu lugar uma definição como a que vimos acima. É como se, com uma única frase, surgisse um ponto de chamada para trabalhar por trás do site.

O fluxo detalhado de criar um Script com um agente de IA é tratado em Criar um backend com uma única frase.

O Script criado é visto e gerenciado por uma pessoa na tela de gerenciamento (o estúdio de conteúdo). Você confere o nome e a definição e, se precisar, altera ou exclui. Quem de fato chama o Script é o site ou o app que o cliente vê (o front-end). Com a identidade de um membro cadastrado no produto (ServiceUser), só é possível executar o Script, não criá-lo nem alterá-lo.

Como se diferencia do Webhook

Tanto o Script quanto o Webhook são mecanismos que ligam ao mundo externo, mas o sentido da chamada é oposto.

O Webhook reage por conta própria quando ocorre uma mudança definida (como um produto sendo cadastrado). Mesmo que ninguém o chame, ele se movimenta sozinho quando o evento acontece. Porém, ele não devolve o resultado a quem o disparou.
O Script é um ponto de chamada que o site chama diretamente quando precisa. Ele só é executado quando é chamado, e o resultado dessa execução é recebido de volta na hora ou, se for execução em segundo plano, por polling.

Para "quando o dono pressiona 'preencher descrição', chamar a IA, receber a descrição detalhada e preenchê-la", quem chama espera o resultado, então o Script é o mais adequado; para "quando um produto é cadastrado, algo acontece automaticamente", trata-se de reagir a um evento, então o Webhook é o mais adequado. E os dois podem ser usados juntos. Vamos ver isso logo a seguir.

A descrição se preenche sozinha só com o cadastro

Até aqui, o dono chamava o Script diretamente, pressionando o botão "preencher descrição". Indo um passo além, é possível fazer com que o Script seja executado sozinho no instante em que um produto é cadastrado, sem que ninguém pressione o botão. Isso acontece porque o Webhook captura esse evento e chama o nosso Script no lugar.

O fluxo é este.

O dono cadastra um produto. Nesse momento, ele preenche apenas o nome do produto e as palavras-chave, e deixa a descrição detalhada em branco.
O Webhook percebe o evento de um produto sendo cadastrado.
O Webhook passa o produto recém-cadastrado tal e qual ao nosso Script "Preencher descrição do produto" e o executa.
O Script gera a descrição detalhada com a IA externa e preenche a descrição detalhada (body) desse produto.
Um instante depois, a descrição detalhada do produto está preenchida sozinha.

Aqui, o Script usado é exatamente o mesmo de antes. O que muda é apenas o gatilho da chamada. Em vez do botão, quem chama é o evento "um produto foi cadastrado". Como o produto cadastrado se torna, tal e qual, a entrada do Script, o Script usa { /payload/sys/id } para pegar esse produto e preencher a descrição detalhada.

Do lado do Webhook, há três coisas a definir. A que evento reagir (quando um produto for cadastrado), a quais produtos reagir apenas (restringir por tipo de produto) e o que fazer (chamar o nosso Script em vez de avisar um endereço externo).

Você pode se preocupar que a descrição detalhada preenchida pelo Script provoque de novo o evento "um produto mudou" e isso se repita sem fim. Não é o caso. A escrita do Script não provoca novos eventos, a menos que você ative isso à parte, e a plataforma também impede a repetição sem fim.

A configuração detalhada dessa ligação é tratada em Webhook.

Quando o Script é especialmente útil

Se a tarefa se resume a apenas avisar o exterior de que "aconteceu algo assim", um Webhook sozinho basta. Mas, quando você precisa chamar um serviço externo e, a partir do resultado, continuar decidindo e processando, é necessário um Script que reúne todo esse fluxo em um só lugar.

Vamos tomar como exemplo uma funcionalidade paga que gera imagens por IA. Quando o cliente pede a geração de uma imagem, as seguintes tarefas precisam acontecer em ordem.

Confere se o cliente tem crédito suficiente. Se faltar, para aqui e avisa "seu crédito é insuficiente".
Se tiver, primeiro deduz o crédito no valor do custo.
Chama o serviço externo de IA e gera a imagem.
Salva a imagem gerada como um Content.
Se ocorrer algum problema na etapa 3 ou 4, devolve o crédito que acabou de ser deduzido.

O Webhook até consegue avisar o exterior de que "chegou uma solicitação", mas não consegue, como aqui, ver o resultado para deduzir o crédito ou reverter o que já foi feito quando algo falha. Encadear várias etapas conforme as condições e, em caso de falha, reverter as etapas anteriores é tarefa do Script. Os casos em que o Script mais faz diferença são os seguintes.

Quando é preciso ver o resultado para continuar o processamento: conforme a resposta devolvida pelo serviço externo, decide ali mesmo se vai salvar, deduzir ou reverter.
Quando não pode haver conflito mesmo com solicitações simultâneas: mesmo que o mesmo cliente faça duas solicitações em um curto intervalo, o crédito não pode ser deduzido duas vezes. Depois de ler o valor e logo antes de salvar, o Script verifica pela versão se "nesse meio-tempo outra solicitação alterou esse valor" e, em caso de conflito, interrompe a operação.
Quando é preciso uma permissão que quem chama não tem: o cliente não tem permissão para alterar por conta própria o saldo de crédito. Ainda assim, a dedução acontece com segurança porque o Script é executado por delegação das permissões de quem o criou. A quem chama, basta conceder a permissão de executar o Script. Essa delegação é tratada em detalhe adiante em Permissão para executar e gerenciar.

Como anotar este exemplo em uma definição real de Script é tratado no exemplo de verificação, dedução e devolução de crédito do Cookbook.

Permissão para executar e gerenciar

Para executar ou gerenciar um Script, a função (SpaceRole) precisa ter a permissão correspondente.

Execução: para chamar um Script, a função precisa ter a permissão de execução de Script (Execute). Sem ela, a execução é bloqueada.
Gerenciamento: para criar, alterar e excluir um Script, são necessárias, respectivamente, as permissões de criação, alteração e exclusão.

Ao executar um Script, a única coisa verificada é se quem chama tem a permissão de execução (Execute), só isso. As ações individuais dispostas dentro do Script não têm a permissão verificada uma a uma no momento da execução. É como quando você chama um programa que tem permissão para rodar: verifica-se apenas a permissão de executar aquele programa, sem pedir autorização a cada uma das coisas que ele faz por dentro.

Em vez disso, a permissão das ações individuais é verificada de antemão não na hora da execução, mas na hora de salvar o Script. Ele só é salvo se quem o criou realmente tiver as permissões de operação sobre Content e Media que as ações dentro do Script manipulam. Por exemplo, o Script "Preencher descrição do produto" altera a descrição detalhada do Content de produto, então, se quem o criou não tiver permissão para alterar o produto, o salvamento é recusado. Um Script que contém uma ação sem permissão não chega a ser salvo.

Visto assim, executar um Script é como realizá-lo em nome de outra pessoa, por delegação das permissões de quem o criou. Mesmo uma operação que quem chama não tem por conta própria, se quem criou o Script pode fazê-la, ela acontece tal e qual por meio do Script. Por isso, ao criar um Script, você precisa decidir com cuidado quais ações colocar dentro dele. As permissões de quem o criou passam a ser o alcance do que aquele Script pode fazer.

Como colocar permissões em uma função é tratado em Função e permissões.

O que é bom saber

Não há publicação. O Script não é o tipo de recurso que se publica para ser entregue aos visitantes; ele é um ponto de chamada que você cria na tela de gerenciamento e que o site chama para usar. Por isso, ao contrário de Content e Media, ele não tem estado de publicação nem de anulação de publicação, e pode ser usado assim que criado. A cada alteração, apenas a versão sobe em um, e, ao excluí-lo, ele é excluído na hora, sem uma etapa prévia como a anulação de publicação.
Há um limite de quantidade. Como o Script é cobrado, a quantidade que uma Organization pode ter é definida conforme o plano (3 no Free, 10 no Basic, 50 no Pro e ilimitado no Enterprise). Ao atingir o limite, você não consegue criar um novo Script, e, ao excluir um Script que não usa, uma vaga fica livre de novo.

Gerenciar no estúdio de conteúdo

O Script criado é visto e gerenciado na tela de Script do estúdio de conteúdo. Ao clicar em Script no menu à esquerda, os Scripts criados até agora aparecem em uma lista. Em cada linha, você vê o nome, a forma de chamar (Método HTTP), o Script ID que identifica o Script, o local de execução (Modo de execução) e a data da última alteração.

Tela de lista de Scripts. O Script "Preencher descrição do produto" aparece em uma linha com método HTTP POST e modo de execução Async

A definição normalmente é criada por um agente de IA no seu lugar, mas você também pode criá-la diretamente nesta tela. Um novo Script é criado com o botão Criar no canto superior direito da lista.

Clique no botão Criar no canto superior direito da lista.
No campo Nome, digite Preencher descrição do produto.
Em Método HTTP, escolha a forma de chamar este Script (aqui, POST).
Em Modo de execução, escolha Async (execução em segundo plano). Este Script chama a IA externa, então precisa obrigatoriamente ser de execução em segundo plano.
No campo Statement, insira a definição com as tarefas. Basta inserir tal e qual a definição do exemplo "Preencher descrição do produto" acima.

Tela de criação de novo Script. Nome "Preencher descrição do produto", método HTTP POST, modo de execução Async e a definição inserida no campo Statement

Se você quiser verificar, antes da execução, a entrada que será enviada junto com a chamada, ative a Validação de Payload em Payload Schema e anote o formato a ser verificado. Depois de preencher tudo, clique no botão Guardar no canto superior direito.

Ao clicar em um Script na lista, a tela de detalhes é aberta. Aqui você confere o nome e a definição e também pode ver o endereço para chamar este Script (a Execute URL). Depois de alterar a definição, ao Guardar, a versão sobe em um, e um Script que você não usa mais é excluído com Eliminar.

Tela de detalhes do Script Preencher descrição do produto. Nome, método HTTP, modo de execução, ID, Execute URL e a definição em Statement visíveis

O que fazer em seguida

Visão geral do Script: trata da estrutura de nível mais alto da definição que forma um Script, das regras de execução e do conjunto de documentos de sintaxe.
Catálogo de Statement: trata dos tipos e dos campos das ações que você pode colocar em statements (criar, ler, alterar e excluir recursos, chamar serviços externos, condições, repetições, entre outras).
Webhook: trata de como fazer algo reagir automaticamente quando ocorre uma mudança definida, como ligar o Script para que ele seja executado sozinho quando um produto é cadastrado.