Catálogo de statements

Cada elemento do array statements é um único statement. Este documento cataloga os campos, o comportamento e o resultado dos 17 tipos de statement. Toda posição de valor segue as regras de Expressões de valor (referência, literal, JsonLogic, mapa de locale).

Resumo dos statements

Chamadas cíclicas são limitadas a 3. As instruções de escrita de recursos acima (ResourceCreate, ResourceUpdate, ResourcePublish etc.) geram eventos de alteração, e esses eventos podem executar um Script novamente por meio de um Webhook. Uma cadeia assim (Script → evento → Webhook → Script → …) continua no máximo 3 vezes. A partir daí, a plataforma a interrompe automaticamente para evitar loops infinitos.

Campos comuns

{ "type": "<StatementType>", "name": "<opcional, único dentro do script>", /* ...campos específicos do tipo... */ }

• type: o discriminador. Um dos valores da tabela acima (obrigatório).
• name: opcional. Se definido, o resultado é vinculado ao contexto em /<name>, de modo que statements posteriores podem referenciá-lo como { /<name>/... }. Omita-o se você não usar o resultado.
• Regras de nome de vínculo: name (e o as de Loop) é uma chave adicionada diretamente à raiz do contexto, por isso é validada ao salvar. Ela não pode ser uma string vazia e não pode conter / nem ~ (precisa poder servir como chave de JSON Pointer), não pode coincidir com as raízes reservadas (payload, vars, error) e deve ser única dentro de um Script. Em caso de violação, o salvamento é rejeitado com WGL400033 (formato), WGL400032 (palavra reservada) ou WGL400034 (duplicidade), respectivamente.

Formato da referência de entidade

Referências de entidade como contentType e target são unificadas em um único formato: { "sys": { "id": <expressão de valor> } }. Apenas sys.id é necessário; o tipo de destino é inferido a partir de resource (sys.type e sys.targetType são omitidos).

• contentType.sys.id geralmente é um literal (ex.: "ct_post").
• target.sys.id geralmente é uma expressão de valor { /ptr } (resolvida em tempo de execução; ex.: { /payload/sys/id }).

resource

Os statements da família de recursos especificam o tipo de destino com resource: "Content" | "Media".

Escritas de recurso

Todo statement de escrita tem propagateEvents (padrão false). Defini-lo como true faz com que essa escrita emita seu próprio EntityEvent (acionando trabalhos subsequentes, como a indexação de busca e Webhooks). O padrão não emite (uma escrita silenciosa do sistema).

ResourceCreate

Cria um Content ou Media. Content e Media compartilham o modelo fields, e os valores são mapas de locale.

• Media file: o valor de fields.file.{locale} é uma instrução de ingestão { "source": <expressão de valor>, "encoding": "url"|"base64" } (ambos obrigatórios). Uma escrita de Media que inclui um arquivo é exclusivamente Async (o motor a processa de forma inline em segundo plano e depois publica; vale para url e base64). Você também pode criar um Media sem arquivo (fileless). Se publish:true mas não houver arquivo ou o processamento estiver incompleto, a etapa de publicação gera erro; se publish:false, permanece Draft.
• Resultado (vínculo de name): o recurso criado. { /<name>/sys/id }, { /<name>/fields/<field>/<locale> }.

// Content
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "fields": { "title": { "en-US": "{ /payload/fields/title }" } }, "publish": true, "name": "post" }
 
// Media. file é uma instrução de ingestão (exclusivamente Async)
{ "type": "ResourceCreate", "resource": "Media",
  "fields": {
    "title": { "en-US": "{ /payload/fields/prompt }" },
    "file":  { "en-US": { "source": "{ /gen/body/data/0/url }", "encoding": "url" } }
  }, "name": "img" }

ResourceUpdate

Substitui totalmente os campos do Content ou Media de destino (PUT). O que você passa em fields se torna o novo conjunto de campos, e todo campo e locale que não estiver presente aqui é removido. Para alterar apenas parte dele, use ResourcePatch.

Se você usar o Update apenas para alterar os metadados de um Media, o file fica de fora e todos os arquivos são excluídos (por ser uma substituição total). Para alterações parciais, use obrigatoriamente ResourcePatch. Um Update que inclui arquivo é exclusivamente Async.

{ "type": "ResourceUpdate", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } },
  "fields": { "title": { "en-US": "Hello", "ko-KR": "안녕" }, "status": { "en-US": "published" } } }

ResourcePatch

Mescla parcialmente os campos do Content ou Media de destino (PATCH). Ela sobrescreve apenas os campos (e os locales dentro deles) que você passa em fields e mantém intactos os campos e locales que você não menciona. O formato dos valores, locale, version e publish são os mesmos de ResourceUpdate.

• Excluir um locale ou arquivo específico: forneça um null literal como valor. Por exemplo: "title": { "fr-FR": null } (exclui o título fr-FR), "file": { "en-US": null } (exclui o arquivo en-US). Uma expressão de valor que é avaliada como null em tempo de execução não é uma exclusão, mas um erro (apenas um null literal exclui).
• Se você fornecer uma instrução de ingestão ao file de Media, ela substitui o arquivo daquele locale (exclusivamente Async). Se você não fornecer um arquivo, ele é mantido.

// +1 apenas em viewCount(en-US). title, outros locales e todo o resto são mantidos como estão
{ "type": "ResourcePatch", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } },
  "fields": { "viewCount": { "en-US": { "+": [ "{ /payload/fields/viewCount }", 1 ] } } } }

ResourceDelete

Exclui o destino. Apenas os status Draft e Archived podem ser excluídos. Se estiver Published ou Changed, a exclusão é rejeitada, portanto você deve fazer ResourceUnpublish primeiro (para Media, também é rejeitada enquanto o arquivo está sendo processado (busy)). Não faz auto-unpublish (igual à CMA/ACMA).

{ "type": "ResourceDelete", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }

ResourcePublish, ResourceUnpublish, ResourceArchive, ResourceUnarchive

Controlam de forma independente o estado de publicação e de arquivamento do destino. Os quatro compartilham os mesmos campos. A pré-condição de status de cada operação é a mesma da CMA/ACMA (a publicação não é permitida a partir de Archived e exige que o processamento do arquivo esteja concluído; a anulação da publicação apenas a partir de Published/Changed; o arquivamento apenas a partir de Draft; o desarquivamento apenas a partir de Archived).

{ "type": "ResourcePublish",   "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }
{ "type": "ResourceUnpublish", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }
{ "type": "ResourceArchive",   "resource": "Media",   "target": { "sys": { "id": "{ /m/sys/id }" } } }

Leituras de recurso

Os statements de leitura não alteram o estado (sem propagateEvents).

Os três statements de leitura usam from (opcional, padrão Current) para definir de qual versão armazenada ler. Current é o rascunho mais recente visto no estúdio de conteúdo (o valor que a CMA/ACMA lê); Published é o snapshot de publicação (o valor no momento da última publicação, entregue pela CDA/ACDA).

Além disso, ResourceFind e ResourcePageRead podem ativar a Busca avançada (Advanced Search) por meio de advanced (opcional, padrão false). É exclusiva de Content, portanto é ignorada nas leituras de Media. Quando ativada, em where é possível usar os operadores regex, near e within e a busca de texto completo (em um campo LongText com a busca de texto completo ativada, eq também encontra os itens que contêm o valor, por correspondência parcial ou aproximada), e order pode ordenar por fields.*. Quando desativada, esses três operadores são rejeitados, eq em texto é correspondência exata, e prefix e os operadores de comparação e de lista funcionam independentemente da busca avançada. Um item recém-criado ou editado leva um breve instante (cerca de 1 segundo) para ser refletido na busca avançada, portanto pode não ser capturado pela consulta de busca avançada imediatamente seguinte. Para ler de imediato um item recém-escrito, use ResourceRead por id (o armazenamento primário, sem esse atraso) ou consulte pelo sys.id que a escrita retornou.

Em where e order, os campos de conteúdo são escritos como fields.<field> (o nome sozinho não é reconhecido). Para fields.<field>, aplica-se automaticamente o locale padrão do Space, portanto você não anexa um locale diretamente. Os fields.status e fields.slug nos exemplos abaixo já são consultas no locale padrão. Somente para direcionar a um locale específico (não padrão), você o indica explicitamente como fields.<field>.<locale> (por exemplo, fields.title.ko-KR). sys.* (como sys.createdAt) e createdBy (:self) são escritos tal como estão, sem fields.. As regras detalhadas estão em Expressões de valor: o locale em where e order.

ResourceRead

Lê um único item por id (get-by-id). O resultado vincula o recurso inteiro ao nome.

• Resultado: referencie { /<name>/sys/id } e { /<name>/fields/<field>/<locale> } diretamente (sem necessidade de items/0).
• Se o destino não existir, gera erro. Você pode envolvê-lo em Try para tratar isso.

{ "type": "ResourceRead", "resource": "Content",
  "target": { "sys": { "id": "{ /payload/fields/orderId }" } }, "name": "order" }

ResourceFind

Lê o primeiro item único correspondente por filtro. Se não houver nenhum, é null. Use-o para encontrar um registro por uma chave de negócio única (slug, email, sku).

• Resultado: vincula o primeiro recurso correspondente ao nome. Referencie-o diretamente como { /<name>/fields/<field>/<locale> }. Como é null quando não há nenhum, ramifique conforme a existência com { "==": [ "{ /<name> }", null ] } (o padrão típico find-then-upsert).

{ "type": "ResourceFind", "resource": "Content", "contentType": { "sys": { "id": "ct_article" } },
  "where": { "fields.slug": { "eq": "{ /payload/fields/slug }" } }, "name": "found" }

ResourcePageRead

Uma leitura com filtro, ordenação e página.

• Resultado: { items, next }. { /<name>/items/0/... }, e a próxima página é { /<name>/next }.
• Para percorrer tudo, use Loop while "{ /vars/hasMore }" junto com cursor e a acumulação de SetVar (veja o Cookbook).

{ "type": "ResourcePageRead", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "where": { "fields.status": { "eq": "draft" } }, "order": "-sys.createdAt", "limit": 100, "name": "page" }

Externo

Http

Chama um endpoint HTTP externo. Quando há Http, executionMode deve ser Async (ExternalIo).

• Resultado: { status, body }. { /<name>/status }, { /<name>/body/... }.
• Limite de tamanho da resposta: O corpo da resposta tem no máximo 10MiB. Se exceder isso, esta chamada falha com uma exceção e pode ser tratada como qualquer outra falha em tempo de execução com Try/catch (é uma falha baseada em tamanho, portanto não é suprimida por ignoreStatusCode).

{ "type": "Http", "method": "POST", "url": "https://api.llm.com/v1/gen",
  "headers": [ { "key": "Authorization", "value": "Bearer sk-...", "secret": true } ],
  "body": { "prompt": "{ /payload/fields/prompt }" }, "timeoutMs": 15000, "retry": 1, "name": "resp" }

Variáveis

SetVar

Declara ou atualiza uma variável mutável com escopo de script. Referencie-a como { /vars/<var> } (o JsonLogic não tem declaração de variável, por isso ela é fornecida como um statement).

{ "type": "SetVar", "var": "total", "value": 0 }
{ "type": "SetVar", "var": "total", "value": { "+": [ "{ /vars/total }", "{ /row/qty }" ] } }   // acumula
{ "type": "SetVar", "var": "ids",   "value": { "merge": [ "{ /vars/ids }", [ "{ /row/sys/id }" ] ] } }  // coleta em array

Controle de fluxo

If

Uma ramificação condicional. condition é JsonLogic, e verdadeiro/falso segue as regras de Avaliação de verdadeiro e falso.

{ "type": "If",
  "condition": { "<": [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] },
  "then": [ { "type": "Return", "value": { "ok": false, "reason": "insufficient credit" } } ],
  "else": [ /* ... */ ] }

Loop

Iteração. Escolha um modo: over (foreach), while (condição) ou for (contado). Em qualquer modo, o motor impõe um limite máximo com maxIterations (para evitar loops infinitos). Chamadas externas dentro de body (Http, ingestão de arquivo de Media) são proibidas.

// foreach
{ "type": "Loop", "over": "{ /payload/fields/items }", "as": "item", "maxIterations": 100,
  "body": [ { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_item" } },
             "fields": { "name": { "en-US": "{ /item/name }" } } } ] }
 
// while
{ "type": "Loop", "while": "{ /vars/hasMore }", "maxIterations": 1000, "body": [ /* ... */ ] }
 
// counted (1..10 step 2)
{ "type": "Loop", "for": { "from": 1, "to": 10, "step": 2 }, "as": "i", "maxIterations": 100, "body": [ /* ... */ ] }

Parallel

Executa as branches de forma concorrente e prossegue após a junção delas. Referências entre branches não são permitidas (se houver uma dependência, coloque-as sequencialmente).

{ "type": "Parallel", "branches": [
  [ { "type": "Http", "method": "GET", "url": "https://api.a.com/x", "name": "a" } ],
  [ { "type": "Http", "method": "GET", "url": "https://api.b.com/y", "name": "b" } ]
] }

Return

É o return da programação comum. Retorna o resultado do Script ao chamador e encerra normalmente naquele ponto.

• Se Return nunca for alcançado, não há valor de retorno. Para retornar um resultado, especifique value explicitamente.
• Por ser um encerramento normal, não uma exceção ou throw, não é alvo de catch (mesmo dentro de Try, encerra o Script inteiro, mas finally ainda é executado).
• Um guard também é expresso com este statement: If combinado com then:[Return] (retorna quando a condição é violada, de modo que o que vem depois não é executado). Este é um de seus vários usos.

{ "type": "Return", "value": { "orderId": "{ /order/sys/id }", "status": "paid" }, "statusCode": 201 }
{ "type": "Return", "value": { "reason": "payment failed" }, "isError": true, "statusCode": 402 }

Try

Tratamento de exceções.

• Se catch o tratar, o Script não é interrompido. Apenas uma falha sem catch interrompe o Script (incluindo uma tentativa de compensação).
• O que conta como "falha" e os limites da compensação são abordados em Semântica de execução, restrições e segurança.

{ "type": "Try",
  "body":    [ { "type": "Http", "method": "POST", "url": "https://primary.api/gen", "name": "resp" },
               { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_result" } },
                 "fields": { "text": { "en-US": "{ /resp/body/text }" } } } ],
  "catch":   [ { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_result" } },
                 "fields": { "text": { "en-US": "Falha na geração" }, "error": { "en-US": "{ /error/message }" } } } ],
  "finally": [ /* sempre é executado */ ] }

Documentos relacionados

• Expressões de valor: as regras de valor que todos os campos acima seguem.
• Semântica de execução, restrições e segurança: ordem de execução, erros, restrições estáticas e segurança.
• Cookbook: exemplos completos que combinam esses statements.
• Visão geral de Script: a estrutura de nível superior e os modos de execução.