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, informando apenas o nome do produto e algumas palavras-chave, uma IA escreva 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, você primeiro 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, você também verá 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 três 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.
• 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.

Veja 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 você verá 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",
  "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 statements.

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.

O Script "Preencher descrição do produto" também é executado no lugar em que foi chamado, e a resposta acima volta na hora. Só que ele contém uma ação que chama a IA externa, então a resposta pode levar alguns segundos para chegar. O tempo disponível para uma execução é tratado abaixo em O tempo dado à execução. A resposta que volta 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 statements.

O tempo dado à execução

O Script é executado no lugar em que foi chamado. Quem o chamou recebe na resposta, de imediato, o resultado daquela execução. Não existe um fluxo em que se pergunta de novo, mais tarde, para buscar o resultado.

O tempo disponível para uma execução tem um orçamento. O padrão é 30 segundos. Se houver uma ação que chama um serviço externo, o orçamento aumenta conforme a espera definida para essa ação. Mesmo aumentando assim, o limite é de 180 segundos.

As ações que repetem algo consomem muito do orçamento. Isso porque o valor reservado é a espera definida para a ação de dentro da repetição multiplicada pelo número de repetições. Se você definir um número de repetições grande, o orçamento também é calculado como algo grande na mesma proporção.

Se o tempo definido for excedido, aquela execução é interrompida ali. O Script "Preencher descrição do produto" chama a IA externa uma vez, então o orçamento deste Script é os 30 segundos padrão mais a espera dessa única chamada.

Quanto de orçamento é reservado por ação e as demais restrições que se aplicam à execução são tratados em Semântica de execução, restrições 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 você viu 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.

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. Isso vem 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.

1. 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.
2. O Webhook percebe o evento de um produto sendo cadastrado.
3. O Webhook passa o produto recém-cadastrado tal e qual ao nosso Script "Preencher descrição do produto" e o executa.
4. O Script gera a descrição detalhada com a IA externa e preenche a descrição detalhada (body) desse produto.
5. 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.

Você pode fazer com que certos Scripts sejam executados somente por meio de um Webhook, como aqui, e impedir que sejam chamados diretamente por um endereço externo. Assim, esse Script só reage aos eventos definidos, e, se for chamado diretamente, a chamada é recusada. A forma de configurar isso é tratada em Recurso e endpoints do Script.

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

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

1. Confere se o cliente tem crédito suficiente. Se faltar, para aqui e avisa "seu crédito é insuficiente".
2. Se tiver, primeiro deduz o crédito no valor do custo.
3. Chama o serviço externo de IA e gera a imagem.
4. Salva a imagem gerada como um Content.
5. 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, é preciso conceder apenas 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, o papel (SpaceRole) precisa ter a permissão correspondente.

• Execução: para chamar um Script, o papel 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 um papel é tratado em Papéis 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 (10 no Free, 30 no Basic, 100 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 da lista aparecem o nome, o Endpoint (a forma de chamar e o endereço são mostrados juntos), se a chamada Anônima é permitida, a hora da modificação e quem modificou.

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.

1. Pressione o botão Criar no canto superior direito da lista.
2. No campo Nome, digite Preencher descrição do produto.
3. Em Método HTTP, escolha a forma de chamar este Script (aqui, POST).
4. No campo Statement, insira a definição com as tarefas. Insira tal e qual a definição do exemplo "Preencher descrição do produto" acima.

A tela de criação tem, além disso, os campos Permitir chamada direta (se você deixar desligado, ele não pode ser chamado pela URL de chamada e só é executado por meio de um Webhook ou de um Scheduler; por padrão vem ligado), Permitir chamada anônima (se você ligar, surge junto um endereço de chamada anônima pelo qual um terceiro pode chamá-lo mesmo sem login na Weegloo; por padrão vem desligado) e URL de chamada (são duas linhas, Padrão e Anônima, e por enquanto estão vazias porque só ficam definidas depois de salvar).

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

Ao clicar em um Script na lista, a tela de detalhes é aberta. A tela de detalhes se divide em duas abas, Log de execução e Definições, e ao abrir pela primeira vez aparece o Log de execução. Na aba Definições você confere o nome e a definição e, à direita, vê junto o número (ID) deste Script, a Versão e as Alterações (hora de criação, quem criou, hora da modificação, quem modificou). Depois de alterar a definição, ao pressionar Guardar, a versão sobe em um. Um Script que você não usa mais é apagado com Eliminar.

Na aba Log de execução vão se acumulando, uma linha por vez, os registros das execuções reais deste Script. Em cada linha você vê Executado em, o que iniciou aquela execução (Origem), o Resultado, a Duração e o ID da requisição que aponta aquela execução. Com a coluna Resultado, na parte de cima, você pode ver só as bem-sucedidas ou só as que falharam, e, ao pressionar Atualizar Logs, os registros das execuções de agora mesmo também são lidos de novo.

Os registros não ficam guardados por muito tempo. As execuções bem-sucedidas são apagadas sozinhas depois de 1 hora, e as que falharam, depois de 3 dias. Como as bem-sucedidas desaparecem primeiro, há momentos em que a lista parece conter apenas falhas.

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 statements: 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.