Objetos de Dados dinâmico

As informações desta página de ajuda se aplicam tanto a Studio quanto a Desktop Studio.

Objetos são uma estrutura de dados que pode conter múltiplos valores em uma única 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.Você pode armazenar todos esses valores em um objeto. A vantagem disso é que isso pode reduzir o número de variáveis usadas em seus Scripts.

Studio oferece suporte a objetos do tipo DynamicData. Esse tipo pode trabalhar com dados que não possuem um formato ou tipo 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 de Chamadas de API.

Você pode usar um objeto de dados dinâmicos em qualquer ação Studio em que possa usar uma variável padrão. objetos de Dados dinâmicos podem ser usados para armazenar dados, assim como variáveis padrão. Elas também têm outros usos. Por exemplo, você pode usá-los para:

O número de variáveis e objetos de dados dinâmicos em um script pode afetar o rastreamento. Você pode notar problemas de desempenho em scripts que contêm um grande número de variáveis dinâmicas. Quanto mais dados eles contiverem, mais tempo pode levar para processar cada ação.

Fatos importantes sobre Objetos de Dados dinâmicos

  • Os valores que um objeto de dados dinâmicos armazena são chamados de membros.
  • Cada membro é identificado por um nome. Por exemplo, em beowulfCharacteristics.occupation, beowulfCharacteristics é o objeto e occupation é o nome de um de seus membros.
  • O tipo dos membros do objeto é determinado em tempo de execução. O compilador salva a informação sobre as propriedades. No tempo de execução, as informações são examinadas e processadas. Por causa disso, o compilador não identifica erros com objetos de dados dinâmicos. Em vez disso, os erros causam exceções de tempo de execução.
  • Objetos de dados dinâmicos podem ter membros criados dinamicamente. Depois de declarar um objeto de dados dinâmicos no script, você atribui valores a membros do objeto nas linhas subsequentes. Você pode até 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 muitos tipos de dados. As variáveis Snippet Padrão são implicitamente tipadas, 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 implicitamente tipados.
  • A sensibilidade a maiúsculas e minúsculas importa ao referenciar os 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 têm 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 esse limite, ele será truncado.

Tente

Baixe o script de Exemplos de Objeto e importe-o para Studio. Alguns dos exemplos desta página de ajuda estão disponíveis em ações Snippet no script de exemplo. Você pode abrir a janela Snippet editor e executar o depurador para ver como cada exemplo funciona.

Membros do objeto

Os objetos de dados dinâmicos armazenam suas propriedades, também chamadas de membros, na forma de pares 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 tem um valor associado a ela, que é colocado 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 que você reduza o número de variáveis que 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 variáveis exclusivas.

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 da sintaxe do Objeto de dados dinâmico

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

Declare um objeto de dados dinâmicos usando esta sintaxe:

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

O <objectName> deve seguir as mesmas diretrizes de nomenclatura que as variáveis padrão em Studio. Os nomes de Objeto diferenciam maiúsculas de minúsculas.

A cláusula 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. Se você usar um 'string', ele deve estar totalmente em uma única linha e entre aspas simples.

Adicione membros a um objeto usando a seguinte sintaxe:

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

Os nomes dos membros diferenciam maiúsculas de minúsculas. Não é necessário usar uma palavra-chave para adicionar membros a um objeto, mas você pode usar ASSIGN se desejar.

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

DYNAMIC <object>

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

Declarar Objetos de Dados dinâmicos

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

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

Não é necessário usar uma palavra-chave para declarar membros do objeto. Você pode usar ASSIGN, se desejar. Referenciar dinamicamente um membro cria o membro se ele ainda não existir.

Consultar um membro de Objeto de Dados dinâmicos

Quando você precisar usar um valor que um objeto de dados dinâmicos contém, deve 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 fazer referência a objetos de dados dinâmicos em qualquer propriedade de ação Studio que aceite substituição de variável, bem como em trechos.

Por exemplo, para fazer referência ao membro name do seguinte objeto, você usaria beowulfCharacteristics.name.

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

Propriedade de Objeto especial $value

Os objetos de dados dinâmicos têm 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á-lo para:

  • Use uma função com um membro de um objeto. Por exemplo: beowulfCharacteristics.name.first.$value.length(). Você pode saber mais sobre a execução de funções com objetos na próxima seção.
  • Copie um valor de uma propriedade de 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 a $value. É somente leitura.

Funções com Objetos

Funções são blocos de código que podem ser chamados e executados no seu script. As 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, existem funções que podem transformar o tipo de letra do valor de uma variável ou membro de objeto. Existem outras funções que podem contar o número de elementos em uma matriz ou informar 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. Você só pode executar funções em membros do objeto, não nos próprios objetos.

Para usar uma função com um objeto, use a propriedade especial do objeto $value. Essa propriedade é somente 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 o valor de string literal do membro do objeto com o qual é usada.

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

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

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

Copiar valores de Objeto para outro Objeto ou Variável

Você pode criar uma cópia dos dados que um objeto contém se quiser duas versões dos dados. Isso permite que você altere uma sem alterar a outra. Para fazer isso, use a função integrada copy() seguindo esta sintaxe:

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

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

A função copy() usa mais recursos do sistema do que atribuir uma referência. Ela realiza uma cópia profunda convertendo o objeto em uma representação textual e, em seguida, novamente em um objeto. Se o objeto com o qual você está trabalhando contiver uma grande quantidade de dados, esse processo pode afetar o funcionamento do script.

Você pode copiar o valor do submembro de um objeto dinâmico para o submembro de outro objeto dinâmico. A função copy() não funciona com submembros, portanto, você precisa definir as variáveis, uma igual a outra:

DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.name

Você pode copiar o valor de um submembro de um objeto dinâmico para uma variável padrão. Isso faz automaticamente com que a variável seja convertida em um objeto dinâmico. Para evitar isso, o nome do objeto dinâmico e do submembro que você está copiando deve estar entre aspas duplas e chaves. Isso evita 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 é adicionar a propriedade $value:

ASSIGN currentContact = beowulfCharacteristics.foe.$value

Atribuir uma Referência a um Valor de Objeto a Outro Objeto ou Variável

Você pode atribuir uma referência de um objeto de dados dinâmicos a 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. Se você alterar o valor de um submembro em qualquer um dos objetos dinâmicos, o valor também será alterado no outro objeto. Por exemplo, se você alterar currentContact.name para Beowulf Herot, o valor de beowulfCharacteristics.name é atualizado automaticamente para Beowulf Herot. Da mesma forma, se você alterar o valor de beowulfCharacteristics.name para Sparky, o valor de currentContact.name será atualizado automaticamente para Sparky.

Não é possível atribuir uma referência a um sub-membro individual. Você pode copiar o valor de um submembro 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âmicos a partir de JSON ou XML

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

Defina o objeto de dados dinâmicos e use o comando FROM para especificar os dados JSON ou XML 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. Se você usar um 'string', ele deve estar inteiramente em uma única linha. Se o 'string' passar para uma segunda linha, isso causa 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 desta forma:

DYNAMIC epicMonsterDoom FROM famousSwords

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

Em Studio, __type (com dois caracteres de sublinhado) é usado ao analisar JSON. Ele não pode ser usado como um nome de chave em variáveis de dados dinâmicos, porque elas podem analisar JSON. Se você usá-lo como um nome de chave em uma variável de dados dinâmicos, isso causará um erro quando você salvar o script ou quando o script executar a ação.

Atribuir uma string JSON a uma Variável

Outra opção ao trabalhar com strings JSON é atribuí-las a uma variável em vez de a 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 seja 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 replace() função para fazer isso 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 da API REST. Essas respostas podem estar em JSON ou xml. Studio as converte em objetos de dados dinâmicos no script. Por exemplo:

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

Neste exemplo, a função MakeRestRequest() retorna um objeto de dados dinâmicos, DynamicReturn. Não é necessário usar a palavra-chave DYNAMIC com essa variável porque o script automaticamente a transforma em um objeto de dados dinâmicos.

Para analisar o objeto de dados dinâmicos que contém a resposta de 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 de API REST

A função asjson() permite preparar dados de carga útil para chamadas de REST API e enviá-los como JSON. O método preferido para esta tarefa é usar a REST API ação. No entanto, você também pode realizar isso 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 armazenar TokenInput em um formato stringified 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âmicos em JSON ou XML

Você pode converter o conteúdo de um objeto dinâmico em 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 você deseja converter. No Studio, você pode fazer isso em um de dois lugares, na ação Snippet action ou na propriedade de ação que precisa dos dados convertidos do objeto.

Ambos os métodos funcionam efetivamente. Entretanto, o benefício de criar uma variável em um Snippet para armazenar o objeto convertido é que isso torna mais fácil ver onde a conversão está ocorrendo. Não é necessário saber qual ação requer o conteúdo convertido do objeto.

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

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

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

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

Todos os membros de um objeto dinâmico são tratados como valores de string, incluindo valores numéricos e BooleanosClosed Um tipo de dados que tem dois valores possíveis: verdadeiro e falso.. 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 replace() função.

Lidar com Caracteres especiais em Chaves JSON

Caracteres especiais em nomes de variáveis causam erros em Studio. Se o JSON com o qual estiver trabalhando tiver chaves com caracteres especiais, você precisará prestar atenção a esta limitação. Por exemplo, isso pode ser um problema ao trabalhar com cabeçalhos que contêm o par de chave-valor CONTENT-TYPE. Quando em um objeto dinâmico, um membro de objeto como requestPayload.HEADERS.CONTENT-TYPE = "APPLICATION/JSON" causaria um erro.

Uma solução é substituir o caractere especial por um texto no objeto dinâmico. Depois de converter o objeto para JSON, substitua o texto pelo caractere especial correto. O exemplo a seguir mostra um membro de objeto dinâmico que contém uma chave CONTENT-TYPE em que o texto HYPHENPLACEHOLDER foi usado no lugar do hífen ( - ):

ASSIGN requestPayload.HEADERS.CONTENTHYPHENPLACEHOLDERTYPE = "APPLICATION/JSON"
ASSIGN requestPayloadJSON = "{requestPayload.asjson()}"
ASSIGN requestPayloadJSON = "{requestPayloadJSON.replace("HYPHENPLACEHOLDER", "-")}"

A segunda e a terceira linhas do exemplo anterior mostram o objeto dinâmico sendo convertido para JSON e, em seguida, a replace() função sendo usada para substituir HYPHENPLACEHOLDER pelo caractere de hífen.

Visualizar Conteúdo de Objetos Dinâmicos

Você pode visualizar o conteúdo de objetos de dados dinâmicos na ferramenta de depuração da ação SNIPPET.

  1. Em Studio, abra um script contendo uma ação Snippet.
  2. Clique em Abrir editor A rectangle with a horizontal line near the top. na ação Snippet.
  3. Adicione o código Snippet, caso ainda não contenha algum.

  4. No lado esquerdo da janela do Snippet editor, clique no ícone de bug Icon of a bug.. O painel Executar & Depurar desliza para fora pelo lado esquerdo da janela.

  5. Clique no triângulo Ícone de um triângulo apontando para a direita. para iniciar a depuração.

  6. Visualize o conteúdo da seção Variáveis do painel Executar & Depurar. Essa seção mostra as variáveis e seus valores quando o depurador tiver executado todo o código do snippet.
  7. Clique em qualquer variável com o valor {Dynamic} para expandi-la e visualizar os valores de seus membros.

Erro de validação de script e Objetos Dinâmicos

Ao salvar um script, Studio valida todas as informações nele contidas. Uma das coisas que ele verifica é 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 que está sendo validado. Mesmo que o objeto esteja declarado em outro script e seja passado para o script que está sendo validado, isso ainda causa o erro. Se houver um objeto não declarado em seu script, você verá um erro "Função '[nome]' não foi definida" ao salvar.

Há duas maneiras de evitar isso. Uma opção é adicionar uma instrução IF com uma variável TEST ao snippet em que você faz referência ao objeto. No conteúdo entre chaves da instruçã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 múltiplos objetos forem passados para o script, você pode declará-los todos em um único SNIPPET. Isso é útil para manter as outras ações SNIPPET organizadas em seu script. Não é preciso conectar esta ação a outras ações no script. Sua existência no script é suficiente para satisfazer a necessidade de declarações de objeto do script durante a validação.