Objeto de dados dinâmicos

Objetos são uma estrutura de dados que podem conter vários valores dentro de uma só variável. Eles são úteis quando você tem uma série de valores relacionados a "algo” no seu script. Por exemplo, você pode ter um conjunto de dados relacionados a um contato, como nome, número de telefone e endereço de email.  É possível armazenar todos esses valores em um objeto. Isso é útil pois permite reduzir o número de variáveis que você usa nos seus scripts.

Studio é compatível com objetos do tipo DynamicData. Este tipo pode trabalhar com dados que não têm um tipo ou formato estático, como XML ou JSON.

Você pode criar objetos de dados dinâmicos declarando-os no código Snippet ou analisando JSON ou XML. Eles também são criados a partir de respostas das chamadas API e determinadas ações de estrutura.

Você pode usar um objeto de dados dinâmicos em qualquer ação Studio onde é possível usar uma variável padrão. Objeto de dados dinâmicos podem ser usados para armazenar dados, assim como variáveis padrões. Eles também têm outros usos. Por exemplo, você pode usá-los para:

• Gerar chamadas da REST API.
• Atender as respostas da ação Workflowdata. Esta ação retorna dados de fluxo de trabalho em um objeto de dados dinâmico.

Fatos importantes sobre objetos de dados dinâmicos

• Os valores que um objeto de dados dinâmicos armazena são chamados membros.
• Cada membro é identificado por um nome. Por exemplo, no beowulfCharacteristics.occupation, beowulf é o objeto e occupation é o nome de um de seus membros.
• O tipo dos membros do objeto são determinados no momento da execução. O compilador salva a informação sobre as propriedades. Na hora da execução, a informação é examinada e acionada. Por causa disso, o compilador não identifica erros com objetos de dados dinâmicos. Em vez disso, os erros causam exceções na hora da execução.
• Objetos de dados dinâmicos podem ter membros criados dinamicamente. Após declarar um objeto de dados dinâmicos no seu script, você atribui valores aos membros do objeto nas linhas seguintes. É possível até mesmo atribuir valores a membros em outros snippets. Se os membros não existirem, eles serão automaticamente criados e os valores especificados serão atribuídos a eles.
• Objetos de dados dinâmicos podem armazenar vários tipos de dados. Variáveis Snippet padrão são digitadas implicitamente, o que significa que o tipo é determinado quando o compilador Studio compila o código.  Objetos de dados dinâmicos são do tipo DynamicData. Os membros de um objeto são digitados implicitamente.
• Letras maiúsculas e minúsculas são distinguidas ao se referenciar membros de um objeto de dados dinâmicos. Por exemplo, se você tentasse analisar o valor de beowulfCharacteristics.files.file com ASSIGN fileContent = "{beowulfcharacteristics.Files.file}", ele não retornaria nada. Isso ocorre porque o membro do objeto dinâmico Files.file não é o mesmo que files.file.
• Todos os membros de objetos de dados dinâmicos possuem uma propriedade especial, $value. Não é possível atribuir um valor a esta propriedade. Ela permite que você desempenhe certas ações com o membro que normalmente você não poderia.
• Objetos de dados dinâmicos e seus membros devem ter menos de 32 KB. Ao converter um objeto para JSON ou XML, o conteúdo resultante deve ser menor do que 32 KB. Se o conteúdo de um objeto convertido exceder este limite, ele aparecerá truncado.

Experimente

Baixe o script de exemplos de objeto e importe-o para o Studio. Alguns dos exemplos desta página de ajuda estão disponíveis nas ações Snippet no script de exemplo. É possível abrir a janela Snippet Editor e executar o depurador para ver como cada exemplo funciona.

Membros de objeto

Objetos de dados dinâmicos contêm suas propriedades, também chamadas de membros, na forma de pares de chave/valor. A chave é o nome do membro e é como o nome de uma variável dentro do objeto. No exemplo a seguir, as chaves são name, occupation e foe. Cada chave possui um valor associado a ela, que fica entre aspas duplas no lado direito do sinal de igual.

DYNAMIC beowulfCharacteristics
beowulfCharacteristics.name = "Beowulf"
beowulfCharacteristics.occupation= "Hero" 
beowulfCharacteristics.foe = "Grendel" 

Objetos de dados dinâmicos permitem reduzir o número de variáveis que você usa em um script. O exemplo anterior mostra como você pode usar um único objeto para armazenar três valores em vez de criar três valores individuais.

Os membros de objetos de dados dinâmicos podem ter seus próprios conjuntos de membros. Esses sub-membros seguem as mesmas regras dos membros primários. Por exemplo:

DYNAMIC beowulfFoes
beowulfFoes.foe1.name = "Grendel"
beowulfFoes.foe1.type = "monster"
beowulfFoes.foe1.status = "defeated"
beowulfFoes.foe2.name = "Grendel's mother"
beowulfFoes.foe2.type = "monster"
beowulfFoes.foe2.status = "defeated" 

Resumo de sintaxe de objetos de dados dinâmicos

Esta seção resume a sintaxe relacionada ao uso de objetos de dados dinâmicos nos scripts do Studio. Você pode aprender mais nas outras seções desta página.

Declare um objeto de dados dinâmicos usando a seguinte sintaxe:

DYNAMIC <objectName> [FROM 'string' | var]

O <objectName> deve seguir as mesmas diretrizes de nomeação das variáveis padrão no Studio. Nomes de objetos diferenciam maiúsculas de minúsculas.

A disposição FROM é opcional. Você pode usá-la para criar um objeto a partir do conteúdo de uma string 'string'ou de uma variável de script varque contenha uma string JSON ou XML. Caso use uma 'string', ela deve estar em uma linha única e entre aspas simples.

Adicione membros a um objeto usando a seguinte sintaxe:

<objectName>.<memberName> = "value".

Nomes de membros diferenciam maiúsculas de minúsculas. Não é preciso usar uma palavra-chave para adicionar membros a um objeto, mas você pode usar ASSIGN se quiser.

Crie uma matriz em um objeto de dados dinâmicos usando a seguinte sintaxe:

DYNAMIC <object>

ASSIGN <object>.<member>[<index>].<sub-member>= "value"

Declarar objetos de dados dinâmicos

Para declarar um objeto de dados dinâmico, use a palavra-chave DYNAMIC em seu código antes do nome da variável e adicione propriedades a ela. Por exemplo:

DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero" 
ASSIGN beowulfCharacteristics.foe = "Grendel"

Você não precisa de uma palavra-chave para declarar membros de objeto. Você pode usar ASSIGN, se quiser. Referenciar dinamicamente um membro cria o membro se ele ainda não existir.

Referir-se a um membro de objeto de dados dinâmicos

Quando você precisa usar um valor que o objeto de dados dinâmicos contém, é preciso se referir ao membro que contém o valor. Use a seguinte sintaxe:

<dynamicObjectName>.<memberName>

É possível usar isso da mesma forma que você faria com uma variável padrão. Você pode referenciar objetos de dados dinâmicos em qualquer propriedade da ação Studio que aceite substituição de variáveis, bem como em snippets.

Por exemplo, para se referir ao membro nome do seguinte objeto, você usaria beowulfCharacteristics.name.

DYNAMIC beowulfCharacteristics
beowulfCharacteristics.name = "Beowulf"
beowulfCharacteristics.occupation= "Hero" 
beowulfCharacteristics.foe = "Grendel" 

Valor de propriedade de objeto especial

Objetos de dados dinâmicos possuem uma propriedade especial, $value. Esta propriedade permite que você realize ações com objetos e seus valores de formas que normalmente não poderia. Você pode usá-la para:

• Usar uma função com um membro de um objeto. Por exemplo: beowulfCharacteristics.name.first.$value.length(). Você pode aprender mais sobre a execução de funções com objetos na próxima seção.
• Copie um valor de uma propriedade de um objeto de dados dinâmicos para uma variável regular usando a propriedade $value: x = name.first.$value

Não é possível atribuir um valor para $value. Ela é somente para leitura.

Funções com objetos

Funções são blocos de código que podem ser chamados e executados no seu script. Funções permitem que você interaja com os valores em uma variável ou objeto. Funções podem modificar valores ou lhe dizer algo sobre eles. Por exemplo, há funções que podem transformar as letras de uma variável ou o valor do membro de um objeto. Há outras funções que podem contar o número de elementos em uma matriz ou lhe dizer se um valor é numérico.

Há uma série de funções disponíveis que você pode usar com objetos de dados dinâmicos nos seus scripts. Só é possível executar funções nos membros de objeto, e não nos próprios objetos.

Para usar uma função com um objeto, use a propriedade especial de objeto $value. Esta propriedade é somente para leitura e não resulta na criação de uma propriedade $value no objeto. Ela impede que o nome da função se torne uma propriedade do objeto. Ela retorna um valor de string literal do membro do objeto com a qual é usada.

Use a seguinte sintaxe para executar uma função em um objeto membro: obj.member.$value.function()

Por exemplo, para executar a função length() no name.first, você usaria:

ASSIGN length = name.first.$value.length().

Copiar valores de objeto para outro objeto ou variável

É possível criar uma cópia dos dados que um objeto armazena caso queira duas versões dos dados. Isso permite que você altere uma sem alterar a outra. Para fazer isto, use a função copy() interna seguindo esta sintaxe:

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

A variável para a qual você copia dados pode ser um objeto dinâmico ou uma variável Studio padrão. Caso seja uma variável padrão, ela será automaticamente convertida em um objeto dinâmico.

É possível copiar o valor de um sub-membro de um objeto dinâmico no sub-membro de outro objeto dinâmico. A função copy() não funciona com sub-membros, portanto será necessário definir as variáveis iguais umas às outras:

DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.name

É possível copiar o valor de um sub-membro de um objeto dinâmico para uma variável padrão. Isso automaticamente faz com que a variável seja convertida em um objeto dinâmico. Para impedir isto, o nome do objeto dinâmico e sub-membro que você está copiando deve estar dentro de aspas duplas e chaves. Isso impede que a variável seja convertida em um objeto dinâmico. Por exemplo:

ASSIGN currentContact = "{beowulfCharacteristics.foe}"

Uma alternativa à formatação do nome do objeto é a adição da propriedade $value.

ASSIGN currentContact = beowulfCharacteristics.foe.$value

Atribuir uma referência a um valor de objeto a um outro objeto ou variável

Você pode atribuir uma referência a um objeto de dados dinâmicos para outro objeto dinâmico. Por exemplo:

DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero" 
ASSIGN beowulfCharacteristics.foe = "Grendel"

DYNAMIC currentContact

ASSIGN currentContact = beowulfCharacteristics

Após a atribuição acima, ambos currentContact e beowulfCharacterics referenciam os mesmos dados físicos. Caso altere o valor de um sub-membro em um dos objetos dinâmicos, o valor também mudará no outro objeto. Por exemplo, se mudar de currentContact.name para Beowulf Herot, o valor de beowulfCharacteristics.name será automaticamente atualizado para Beowulf Herot. Da mesma forma, se mudar o valor de beowulfCharacteristics.name para Sparky, o valor de currentContact.name será automaticamente atualizado para Sparky.

Não é possível atribuir uma referência a um sub-membro individual. É possível copiar o valor de um sub-membro de um objeto dinâmico para outro. Isso reproduz o valor. Se alterar o valor de um, o valor do outro não será automaticamente mudado.

Criar um objeto de dados dinâmico de JSON ou XML

Você pode usar um objeto de dados dinâmico para analisar JSON ou XML.

Defina o objeto de dados dinâmicos e use o comando FROM para especificar os dados XML ou JSON com esta sintaxe:

DYNAMIC <objectName> [FROM 'string' | var]

Você pode especificar um 'string' que contém dados JSON ou XML. Também é possível especificar o nome de uma variável de script var que contenha uma string JSON ou dados XML. Caso use uma 'string', ela deve estar em uma linha única. Se 'string' for dividido para uma segunda linha, ocorrerá um erro.

Por exemplo:

DYNAMIC beowulfWeapons FROM '{ "key1": "Hrothgars gift", "key2": "Hrunting", "key3": "Naegling"}'

Os resultados disso são:

beowulfWeapons.key1 = "Hrothgars gift"  
beowulfWeapons.key2 = "Hrunting" 
beowulfWeapons.key3 = "Naegling"

Se os pares de chave-valor JSON usados no exemplo anterior estivessem contidos em uma variável chamada famousSwords, você poderia criar o objeto de dados dinâmicos da seguinte forma:

DYNAMIC epicMonsterDoom FROM famousSwords

Os resultados são os mesmos com ambos os métodos de criação do objeto.

Atribuir uma string JSON a uma variável

Outra opção ao se trabalhar com strings JSON é atribuí-las a uma variável em vez de um objeto dinâmico. Este não é o método ideal para se trabalhar com strings JSON. Ele não lhe dá a flexibilidade de gerenciar e trabalhar com seu código que os objetos dinâmicos com JSON dão. No entanto, pode haver ocasiões em que isso se faz necessário.

Antes que possa atribuir uma string JSON a uma variável, você deve substituir os caracteres de chave ( { ) e aspa dupla ( " ) com caracteres de escape. Você pode usar um editor de texto para substituir os caracteres manualmente ou a função replace() para fazê-lo no script. Na atribuição de variável, a string JSON deve ser precedida por um sinal de dólar ( $ ), conforme mostrado no exemplo a seguir: O sinal de dólar indica um valor que contém os caracteres de escape.

ASSIGN customPayloadFromBotJson = $"\{\"prompts\": [\{\"mediaSpecificObject\": \{\"dfoMessage\": \{\"messageContent\": \{\"type\": \"PLUGIN\", \"payload\": \{\"elements\": [\{\"id\": \"bf2521f4-5e85-413f-b6ed-815d1c3905f0\", \"type\": \"FILE\", \"filename\": \"photo.jpg\", \"url\": \"https://www.nice.com/-/media/niceincontact/layout/nice-logo-web-header/nice-web-logo.ashx\", \"mimeType\": \"image/jpeg\"}]}}}}}]}"
		

Criar um objeto de dados dinâmicos a partir de uma resposta REST

Os objetos de dados dinâmicos são criados automaticamente a partir de respostas de chamadas do API REST. Essas respostas podem ser em JSON ou XML. Studio converte-os em objetos de dados dinâmicos em um script. Por exemplo:

ASSIGN GetRequest = "<API Endpoint>"
ASSIGN DynamicReturn = Proxy.MakeRestRequest(GetRequest,"",0,"GET")
ASSIGN fileContent = "{DynamicReturn.files.file}"

Nesse exemplo, a função MakeRestRequest() retorna um objeto de dados dinâmico, DynamicReturn. Você não precisa usar a palavra-chave DYNAMIC com esta variável porque o script automaticamente a torna um objeto de dados dinâmico.

Para analisar o objeto de dados dinâmico que contém a resposta REST, use ASSIGN fileContent = "{DynamicReturn.files.file}". Isso atribui o valor extraído ({DynamicReturn.files.file}) para a variável fileContent. Você também pode usar ASSIGN fileContent = DynamicReturn.files.file.$value para analisar a resposta.

Preparar dados de carga útil para chamadas REST API

É possível preparar dados de carga útil para chamadas do REST API e enviá-las como JSON usando a função asjson(). O método preferencial para esta tarefa é o uso da ação REST API. No entanto, você também pode realizá-la em um snippet. Por exemplo:

DYNAMIC tokenInput
ASSIGN tokenInput.grant_type = "password"
ASSIGN tokenInput.username = "Grendel.Cainson"
ASSIGN tokenInput.password = "MadeUpPassword"
	<additional tokenInput properties> 
ASSIGN tokenJsonInput = "{tokenInput.asjson()}"
ASSIGN proxy = GETRESTProxy()
<ASSIGN additional variables as needed>
ASSIGN tokenResponse = proxy.MakeRestRequest(TokenRequestURL,TokenJsonInput, 0, "POST")

Neste exemplo, TokenInput é declarado como um objeto dinâmico com três membros, grant_type, username e password. TokenJsonInput é declarado para conter TokenInput em uma forma de string usando a função asjson(). Na última linha do exemplo, a variável TokenResponse é declarada para manter a solicitação REST, que pode ser usada no código do script para enviar a solicitação.

Converter um objeto de dados dinâmico para JSON ou XML

Você pode converter os conteúdos de um objeto dinâmico para uma string JSON ou XML. Isso serializa os dados no objeto e os coloca em um formato que pode ser transmitido pela Internet.

Para fazer isso, use a função asjson() ou asxml() com o objeto que deseja converter. No Studio, você pode fazer isto em dois lugares diferentes: em uma ação Snippet ou na propriedade da ação que precisa dos dados convertidos do objeto.

Ambos os métodos funcionam efetivamente. No entanto, a vantagem de criar uma variável em um Snippet para conter o objeto convertido é que ele torna mais fácil ver onde a conversão está acontecendo. Você não precisa saber qual ação precisa dos conteúdos convertidos do objeto.

Para converter um objeto em um Snippet, use a seguinte sintaxe:

ASSIGN varJSON="{myDynamic.asjson()}"

Na propriedade da ação Studio onde você precisa dos dados em JSON ou XML, use o nome da variável que usou no Snippet. Com a sintaxe de exemplo, você configuraria a propriedade da ação com varJSON.

Para converter um objeto na propriedade da ação, configure a propriedade da ação com o nome do objeto e asjson() ou a função asxml() dentro de chaves. Por exemplo: {myDynamic.asjson()}.

Todos os membros de um objeto dinâmico são tratados como valores de string, incluindo os valores numéricos e booleanos Um tipo de dados que tem dois valores possíveis: true e false.. Para valores que não são strings, será preciso analisar manualmente o JSON para remover as aspas duplas. Você pode fazer isso usando a função replace().

Ver conteúdo de objetos dinâmicos

Você pode ver os conteúdos de objetos dinâmicos na janela do editor Snippet quando executa o depurador. Isto permite que você verifique se o objeto contém dados que deveria conter a cada etapa do seu código.

1. No Studio, clique duas vezes em uma ação Snippet.
2. Adicione o código do snippet, se necessário.
3. Na guia Debugger , clique na guia Variáveis em árvore.
4. Na guia Debugger , clique na seta para baixo ao lado do ícone Começar depuração e selecione Avançar para . Caso não queira avançar pelo código linha por linha, clique no ícone Começar depuração.
5. Clique no ícone Avançar e observe os conteúdos na guia Variables as Tree. Toda vez que você clica em Avançar, este campo é atualizado com as variáveis e objetos no script após a linha anterior de código. Pule esta etapa se já tiver clicado em Começar depuração.
6. Quando tiver avançado por todas as linhas de código ou clicado em Começar depuração, a guia Variables as Tree exibe todas as variáveis, objetos e seus conteúdos ao fim do snippet.

7. Você pode clicar no ícone + ao lado de qualquer conjunto de strings ou objetos dinâmicos no código para expandi-los. Se o conteúdo for outro conjunto ou objeto, é possível continuar a expandir a árvore para ver o que cada entidade contém.

   Ver imagem

   

Erro de validação de script e objetos dinâmicos

Ao salvar um script, Studio valida toda a informação nele. Uma das coisas que são verificadas é se todos os objetos dinâmicos referenciados no script estão declarados no script. Studio exige uma declaração de objeto para todos os objetos referenciados no script sendo validados. O erro ocorrerá mesmo se o objeto tiver sido declarado em outro script e passado ao que está sendo validado. Caso tenha um objeto não declarado no seu script, verá um erro “Função '[nome]' não foi definida” ao salvar.

Há duas maneiras de evitar isso. Uma opção é adicionar uma expressão IF com uma variável TEST ao snippet onde referencia o objeto. Dentro das chaves da expressão IF, declare o objeto dinâmico. Por exemplo:

IF TEST = 1
{
	DYNAMIC dynaObject
}
DYNAMIC dynaObject.prop = 1

A segunda opção é adicionar um SNIPPET ao script que contém a declaração do objeto e nada mais. Se vários objetos forem passados ao script, é possível declarar todos em um único SNIPPET. Isto é útil para manter as outras ações SNIPPET no seu script organizadas. Não é preciso conectar esta ação a outras ações no script. A sua existência no script é suficiente para satisfazer a necessidade do script por declarações de objetos durante a validação.