Objetos de Datos dinámicos

Los objetos son una estructura de datos que puede contener múltiples valores dentro de una sola variable. Son útiles cuando se tiene un conjunto de valores que se relacionan con una "cosa" en el script. Por ejemplo, podría tener un conjunto de datos relacionados con un contacto, como el nombre, el número de teléfono y la dirección de correo electrónico. Puede almacenar todos estos valores en un objeto. El beneficio de esto es que puede reducir la cantidad de variables usadas en sus scripts.

Studio admite objetos del tipo DynamicData. Este tipo puede trabajar con datos que no tienen un formato o tipo estático, como XML o JSON.

Puede crear objetos de datos dinámicos declarándolos en el código de Snippet o analizando JSON o XML. También se crean a partir de respuestas de llamadas a la API.

Puede usar un objeto de datos dinámicos en cualquier acción de Studio donde pueda usar una variable estándar. Los objetos de Datos dinámicos se pueden usar para almacenar datos, al igual que las variables estándar. También tienen otros usos. Por ejemplo, puede usarlos para:

• Generar llamadas a la API REST.
• Manejar las respuestas de la Workflowdata action. Esta Acción devuelve datos de flujo de trabajo en un objeto de datos dinámicos.

Datos clave sobre los Objetos Dinámicos de Datos

• Los valores que almacena un objeto dinámico de datos se denominan miembros.
• Se identifica a cada miembro con un nombre. Por ejemplo, en beowulfCharacteristics.occupation, beowulfCharacteristics es el objeto y occupation es el nombre de uno de sus miembros.
• El tipo de los miembros del objeto se determina en tiempo de ejecución. El compilador guarda la información sobre las propiedades. En tiempo de ejecución, la información se examina y se actúa en consecuencia. Debido a esto, el compilador no detecta errores con los objetos de datos dinámicos. En cambio, los errores provocan excepciones en tiempo de ejecución.
• Los objetos de datos dinámicos pueden tener miembros creados dinámicamente. Después de declarar un objeto de datos dinámicos en su script, asigna valores a los miembros del objeto en líneas posteriores. Incluso puede asignar valores a miembros en otros snippets. Si los miembros no existen, se crean automáticamente y se les asignan los valores especificados.
• Los objetos de datos dinámicos pueden almacenar muchos tipos de datos. Las variables Estándar de Snippet tienen tipo implícito, lo que significa que el tipo se determina cuando el compilador de Studio compila el código. Los objetos de Datos dinámicos son del tipo DynamicData. Los miembros de un objeto se escriben implícitamente.
• La distinción entre mayúsculas y minúsculas importa al hacer referencia a los miembros de un objeto de datos dinámicos. Por ejemplo, si intentara analizar el valor de beowulfCharacteristics.files.file con ASSIGN fileContent = "{beowulfcharacteristics.Files.file}", no devolvería nada. Esto se debe a que el miembro del objeto dinámico Files.file no es lo mismo que files.file.
• Todos los miembros de los objetos de datos dinámicos tienen una propiedad especial, $value. No se puede asignar un valor a esta propiedad. Permite realizar ciertas acciones con el miembro que, de otro modo, no funcionarían.
• Los objetos de datos dinámicos y sus miembros deben tener menos de 32 KB. Al convertir un objeto a JSON o XML, el contenido resultante debe tener menos de 32 KB. Si el contenido convertido de un objeto excede ese límite, se le trunca.

Pruébelo

Descargue el script de ejemplos de Objetos e impórtelo en Studio. Algunos de los ejemplos de esta página de ayuda están disponibles en acciones de Snippet en el script de ejemplo. Puede abrir la ventana de Snippet editor y ejecutar el depurador para ver cómo funciona cada ejemplo.

Miembros del Objeto

Los objetos de datos dinámicos contienen sus propiedades, también llamadas miembros, en forma de pares clave/valor. La clave es el nombre del miembro y es como el nombre de una variable dentro del objeto. En el siguiente ejemplo, las claves son name, occupation y foe. Cada clave tiene un valor asociado, que está encerrado entre comillas dobles en el lado derecho del signo igual.

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

Los objetos de datos dinámicos le permiten reducir la cantidad de variables que usa en un script. El ejemplo anterior muestra cómo puede usar un solo objeto para contener tres valores en lugar de crear tres variables únicas.

Los miembros de los objetos de datos dinámicos pueden tener sus propios conjuntos de miembros. Estos submiembros siguen las mismas reglas que los miembros de primer nivel. Por ejemplo:

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" 

Resumen de la sintaxis de Objetos de Datos dinámicos

Esta sección resume la sintaxis relacionada con el uso de objetos de datos dinámicos en scripts de Studio. Puede obtener más información en las otras secciones de esta página.

Declare un objeto dinámico de datos usando esta sintaxis:

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

El <objectName> debe seguir las mismas pautas de nomenclatura que las variables estándar en Studio. Los nombres de los Objetos distinguen entre mayúsculas y minúsculas.

La cláusula FROM es opcional. Puede usarla para crear un objeto a partir del contenido de una cadena 'string'o una variable de script varque contenga una cadena JSON o XML. Si usa un 'string', debe estar completamente en una sola línea y entre comillas simples.

Agregue miembros a un objeto usando esta sintaxis:

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

Los nombres de los miembros distinguen entre mayúsculas y minúsculas. No es necesario usar una palabra clave para agregar miembros a un objeto, pero puede usar ASSIGN si lo desea.

Cree un arreglo en un objeto dinámico de datos usando esta sintaxis:

DYNAMIC <object>

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

Declarar Objetos de Datos dinámicos

Para declarar un objeto de datos dinámicos, use la palabra clave DYNAMIC en su código antes del nombre de la variable y luego agréguele propiedades. Por ejemplo:

DYNAMIC beowulfCharacteristics

ASSIGN beowulfCharacteristics.name = "Beowulf"

ASSIGN beowulfCharacteristics.occupation= "Hero" 

ASSIGN beowulfCharacteristics.foe = "Grendel"

No necesita una palabra clave para declarar miembros de objetos. Puede usar ASSIGN, si lo desea. Hacer referencia a un miembro crea dinámicamente el miembro si aún no existe.

Hacer referencia a un Miembro de un Objeto Dinámico de Datos

Cuando necesite usar un valor que contiene un objeto de datos dinámicos, debe hacer referencia al miembro que contiene el valor. Use la siguiente sintaxis:

<dynamicObjectName>.<memberName>

Puede usar esto de la misma manera en que usaría una Variable estándar. Puede hacer referencia a objetos de datos dinámicos en cualquier propiedad de acción de Studio que acepte sustitución de variables, así como en snippets.

Por ejemplo, para hacer referencia al nombre del miembro del siguiente objeto, tiene que usar beowulfCharacteristics.name.

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

Propiedad especial de Objeto $value

Los objetos de datos dinámicos tienen una propiedad especial, $value. Esta propiedad le permite hacer cosas con los objetos y sus valores de maneras que de otro modo no serían posibles. Puede usarla para:

• Usar una función con un miembro de un objeto. Por ejemplo: beowulfCharacteristics.name.first.$value.length(). Puede obtener más información sobre cómo ejecutar funciones con objetos en la siguiente sección.
• Copiar un valor de una propiedad de objeto de datos dinámicos en una Variable normal mediante la propiedad $value: x = name.first.$value.

No puede asignar un valor a $value. Es de solo lectura.

Funciones con Objetos

Las Funciones son bloques de código que se pueden llamar y ejecutar en su script. Las Funciones le permiten interactuar con los valores de una Variable o un objeto. Las Funciones pueden modificar valores o indicarle algo sobre ellos. Por ejemplo, hay funciones que pueden transformar las mayúsculas y minúsculas del valor de una Variable o de un miembro de un objeto. Hay otras funciones que pueden contar la cantidad de elementos en una matriz o indicarle si un valor es numérico.

Hay disponibles varias funciones que puede usar con los objetos de datos dinámicos en sus scripts. solo puede ejecutar funciones en miembros de objetos, no en los objetos en sí.

Para usar una función con un objeto, use la propiedad especial de objeto $value. Esta propiedad es de solo lectura y no da como resultado la creación de una propiedad $value en el objeto. Evita que el nombre de la función se convierta en una propiedad del objeto. Devuelve el valor de la cadena literal del miembro del objeto con el que se utiliza.

Use la siguiente sintaxis para ejecutar una función en un miembro de un objeto: obj.member.$value.function().

Por ejemplo, para ejecutar la función length() en name.first, usaría:

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

Copiar valores de Objeto a otro Objeto o Variable

Puede crear una copia de los datos que contiene un objeto si desea tener dos versiones de los datos. Esto le permite cambiar uno sin afectar al otro. Para hacerlo, use la Función integrada copy() función siguiendo esta sintaxis:

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

La Variable en la que copia datos puede ser un objeto dinámico o una Variable estándar de Studio. Si es una Variable estándar, se convierte automáticamente en un objeto dinámico.

Puede copiar el valor del submiembro de un objeto dinámico en el submiembro de otro objeto dinámico. La función copy() no funciona con submiembros, por lo que debe establecer que las variables sean iguales entre sí:

DYNAMIC currentContact

currentContact.who = beowulfCharacteristics.name

Puede copiar el valor del submiembro de un objeto dinámico en una variable estándar. Esto hace que la variable se convierta automáticamente en un objeto dinámico. Para evitarlo, el nombre del objeto dinámico y el submiembro que está copiando deben estar entre comillas dobles y llaves. Esto evita que la variable se convierta en un objeto dinámico. Por ejemplo:

ASSIGN currentContact = "{beowulfCharacteristics.foe}"

Un alternativo para dar formato al nombre del objeto es agregar la propiedad $value:

ASSIGN currentContact = beowulfCharacteristics.foe.$value

Asignar una Referencia al valor de un Objeto a otro Objeto o variable

Puede asignar una referencia a un objeto de datos dinámicos a otro objeto dinámico. Por ejemplo:

DYNAMIC beowulfCharacteristics

ASSIGN beowulfCharacteristics.name = "Beowulf"

ASSIGN beowulfCharacteristics.occupation= "Hero" 

ASSIGN beowulfCharacteristics.foe = "Grendel"



DYNAMIC currentContact



ASSIGN currentContact = beowulfCharacteristics

Después de la asignación anterior, currentContact y beowulfCharacterics hacen referencia a los mismos datos físicos. Si cambia el valor de un submiembro en cualquiera de los objetos dinámicos, el valor también cambia en el otro objeto. Por ejemplo, si cambia currentContact.name a Beowulf Herot, el valor de beowulfCharacteristics.name se actualiza automáticamente a Beowulf Herot. De manera similar, si cambia el valor de beowulfCharacteristics.name a Sparky, el valor de currentContact.name se actualiza automáticamente a Sparky.

No puede asignar una referencia a un submiembro individual. Puede copiar el valor de un submiembro de un objeto dinámico a otro. Esto duplica el valor. Si cambia el valor de uno, no cambia automáticamente el otro valor.

Crear un Objeto de Datos dinámicos a partir de JSON o XML

Puede utilizar un objeto dinámico de datos para analizar JSON o XML.

Defina el objeto dinámico de datos y utilice el comando FROM para especificar los datos JSON o XML con esta sintaxis:

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

Puede especificar un 'string' que contenga datos JSON o XML. También puede especificar el nombre de una variable de script var que contenga una cadena JSON o datos XML. Si utiliza un 'string', debe estar completamente en una sola línea. Si el 'string' se divide en una segunda línea, provocará un Error.

Por ejemplo:

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

Los resultados de esto son:

beowulfWeapons.key1 = "Hrothgars gift"  

beowulfWeapons.key2 = "Hrunting" 

beowulfWeapons.key3 = "Naegling"

Si los pares clave-valor JSON que se utlizan en el ejemplo anterior estuvieran contenidos en una variable llamada famousSwords, podría crear el objeto dinámico de datos de esta manera:

DYNAMIC epicMonsterDoom FROM famousSwords

Los resultados son los mismos con ambos métodos de creación del objeto.

Asignar una cadena JSON a una variable

Otra opción al trabajar con cadenas JSON es asignarlas a una variable en lugar de a un objeto dinámico. Este no es el método preferido para trabajar con cadenas JSON. No ofrece la flexibilidad de administrar y trabajar con su código que sí ofrece tener JSON en objetos dinámicos. Sin embargo, puede haber ocasiones en las que sea necesario.

Antes de poder asignar una cadena JSON a una variable, debe reemplazar los caracteres de llave ( { ) y comillas dobles ( " ) por caracteres de escape. Puede utilizar un Editor de texto para reemplazar los caracteres manualmente o la función replace() function para hacerlo en el script. En la asignación de la variable, la cadena JSON debe tener como prefijo un signo de dólar ( $ ), como se muestra en el siguiente ejemplo. El signo de dólar indica un valor que contiene 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\"}]}}}}}]}"

		

Crear un Objeto de Datos dinámicos a partir de un Response REST

Los objetos de datos dinámicos se crean automáticamente a partir de respuestas de llamadas a la API de REST. Estas respuestas pueden estar en formato JSON o XML. Studio los convierte en objetos de datos dinámicos en el script. Por ejemplo:

ASSIGN GetRequest = "<API Endpoint>"

ASSIGN DynamicReturn = Proxy.MakeRestRequest(GetRequest,"",0,"GET")

ASSIGN fileContent = "{DynamicReturn.files.file}"

En este ejemplo, la función MakeRestRequest() devuelve un objeto de datos dinámicos, DynamicReturn. No es necesario utilizar la palabra clave DYNAMIC con esta variable porque el script la convierte automáticamente en un objeto de datos dinámicos.

Para analizar el objeto de datos dinámicos que contiene la respuesta de REST, use ASSIGN fileContent = "{DynamicReturn.files.file}". Esto asigna el valor extraído ({DynamicReturn.files.file}) a la variable fileContent. También puede usar ASSIGN fileContent = DynamicReturn.files.file.$value para analizar la respuesta.

Preparar datos de Carga útil para llamadas de REST API

Puede preparar datos de carga útil para llamadas de REST API y enviarlos como JSON mediante la función asjson(). El método preferido para esta tarea es usar la REST API acción. Sin embargo, también puede lograrlo en un snippet. Por ejemplo:

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")

En este ejemplo, TokenInput se declara como un objeto dinámico con tres miembros, grant_type, username y password. TokenJsonInput se declara para contener TokenInput en forma de cadena de texto mediante la función asjson(). En la última línea del ejemplo, la variable TokenResponse se declara para contener la solicitud de REST, que luego se puede usar en el código del script para enviar la solicitud.

Convertir un Objeto de Datos dinámicos a JSON o XML

Puede convertir el contenido de un objeto dinámico a una cadena de texto JSON o XML. Esto serializa los datos en el objeto y los coloca en un formato que se puede transmitir a través de Internet.

Para hacer esto, use la función asjson() o asxml() con el objeto que desea convertir. En Studio, puede hacer esto en uno de dos lugares, ya sea en una Acción de Snippet acción o en la propiedad de la acción que necesita los datos convertidos del objeto.

Ambos enfoques funcionan por igual. Sin embargo, el beneficio de crear una variable en un Snippet para contener el objeto convertido es que facilita ver dónde ocurre la conversión. No necesita saber qué acción requiere el contenido convertido del objeto.

Para convertir un objeto en un Snippet, use la siguiente sintaxis:

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

En la propiedad de la acción Studio donde necesita los datos JSON o XML, use el nombre de la variable que utilizó en el Snippet. Según el ejemplo de sintaxis, configuraría la propiedad de la acción con varJSON.

Para convertir un objeto en la propiedad de la acción, configure la propiedad de la acción con el nombre del objeto y la función asjson() o asxml() entre llaves. Por ejemplo: {myDynamic.asjson()}.

Todos los miembros de un objeto dinámico se tratan como valores de cadena de texto, incluidos los valores numéricos y booleanos Un tipo de datos que tiene dos valores posibles: verdadero y falso.. Para los valores que no son cadenas de texto, debe analizar manualmente el JSON para quitar las comillas dobles. Puede hacer esto mediante la función replace().

Manejar Caracteres especiales en las Teclas JSON

Los caracteres especiales en los nombres de variable causan errores en Studio. Si el JSON con el que trabaja tiene claves con caracteres especiales en el nombre, debe encontrar una solución alternativa para esta limitación. Por ejemplo, esto puede ser un problema al trabajar con encabezados que contienen el par clave-valor CONTENT-TYPE. Cuando se encuentra en un objeto dinámico, un miembro de objeto como requestPayload.HEADERS.CONTENT-TYPE = "APPLICATION/JSON" causaría un error.

Una solución es reemplazar el carácter especial con texto en el objeto dinámico. Después de convertir el objeto a JSON, reemplace el texto con el carácter especial correcto. El siguiente ejemplo muestra un miembro de objeto dinámico que contiene una clave CONTENT-TYPE donde se ha usado el texto HYPHENPLACEHOLDER en lugar del guion ( - ):

ASSIGN requestPayload.HEADERS.CONTENTHYPHENPLACEHOLDERTYPE = "APPLICATION/JSON"

ASSIGN requestPayloadJSON = "{requestPayload.asjson()}"

ASSIGN requestPayloadJSON = "{requestPayloadJSON.replace("HYPHENPLACEHOLDER", "-")}"

Las líneas segunda y tercera del ejemplo anterior muestran el objeto dinámico que se convierte en JSON y, luego, la función replace() que se utiliza para reemplazar HYPHENPLACEHOLDER con el caractere de guion.

Ver el Contenido de los Objetos Dinámicos

Puede ver el contenido de los objetos de datos dinámicos en la herramienta de depuración de la acción SNIPPET.

1. En Studio, abra un script que contenga una acción Snippet.
2. Haga clic en Abrir editor en la acción Snippet.

3. Agregue código Snippet si todavía no contiene alguno.

4. En el lado izquierdo de la ventana del editor de Snippet, haga clic en el ícono de insecto . El panel Ejecutar y Depurar se despliega desde el lado izquierdo de la ventana.

5. Haga clic en el triángulo para comenzar la depuración.

6. Vea el contenido de la sección Variables del panel Ejecutar y Depurar. Esta sección muestra las variables y sus valores una vez que el depurador ha ejecutado todo el código del snippet.
7. Haga clic en cualquier variable con el valor {Dynamic} para expandirla y ver los valores de sus miembros.

Error de validación de script y Objetos Dinámicos

Cuando guarda un script, Studio valida toda la información que contiene. Una de las cosas que verifica es que todos los objetos dinámicos a los que se hace referencia en el script estén declarados en él. Studio requiere una declaración de objeto para todos los objetos a los que se hace referencia en el script que se está validando. Incluso si el objeto está declarado en otro script y se pasa al que se está validando, igualmente provoca el error. Si en su script tiene un objeto no declarado, verá un error "No se ha definido la función ‘[nombre]’" al guardarlo.

Hay dos formas de evitar esto. Una opción es agregar una instrucción IF con una variable TEST al snippet donde hace referencia al objeto. En las llaves de la instrucción IF, declare el objeto dinámico. Por ejemplo:

IF TEST = 1

{

	DYNAMIC dynaObject

}

DYNAMIC dynaObject.prop = 1

La segunda opción es agregar un SNIPPET al script que contenga la declaración del objeto y nada más. Si se pasan varios objetos al script, puede declararlos todos en un único SNIPPET. Esto es útil para mantener ordenadas las demás acciones SNIPPET de su script. No es necesario conectar esta acción con otras acciones del script. Su existencia en el script es suficiente para cumplir con la necesidad de que en el script se declaren los objetos durante la validación.