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 una colección de valores que se relacionan todos con una "cosa" en su script. Por ejemplo, usted puede tener un conjunto de datos relacionados con un contacto, como nombre, número de teléfono y dirección de correo electrónico.  Puede almacenar todos estos valores en un objeto. El beneficio de hacer esto es que puede reducir la cantidad de variables que use en sus scripts.

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

Puede crear objetos de datos dinámicosdeclarándolos enRetazo código o poranalizando JSON o XML. También se crean a partir de respuestas a llamadas la API y ciertas acciones del Marco.

Puede utilizar un objeto dinámico de datos en cualquier acción Studio donde pueda utilizar una variable estándar. Se pueden utilizar los objetos dinámicos de datos para almacenar datos, al igual que las variables estándar. Pero también tienen otros usos. Por ejemplo, puede usarlos para:

• Generar llamadas a la API REST.
• Manejar las respuestas de la Workflowdata acción. 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, beowulf es el objeto y occupation es el nombre de uno de sus miembros.
• En tiempo de ejecución se determina el tipo de miembros del objeto. El compilador guarda la información sobre las propiedades. En tiempo de ejecución, se analiza la información y se actúa según corresponda. Debido a esto, el compilador no detecta errores con los objetos dinámicos de datos. Por el contrario, los errores provocan excepciones en tiempo de ejecución.
• Los objetos dinámicos de datos pueden tener miembros que se generen dinámicamente. Después de declarar un objeto dinámico de datos en su script, usted asigna valores a los miembros del objeto en las líneas siguientes. Incluso puedes asignar valores a los miembros en otros snippets. Si no existen los miembros, se crean automáticamente y se les asignan los valores especificados.
• Los objetos dinámicos de datos pueden almacenar muchos tipos de datos. Las variables estándar de los Snippets se escriben implícitamente, lo que significa que se determina el tipo cuando el compilador Studio compila el código.  Los objetos dinámicos de datos son del tipo DynamicData. Los miembros de un objeto se escriben implícitamente.
• Es importante la distinción entre mayúsculas y minúsculas al hacer referencia a los miembros de un objeto dinámico de datos. Por ejemplo, si intenta analizar el valor de beowulfCharacteristics.files.file con ASSIGN fileContent = "{beowulfcharacteristics.Files.file}", no se devolverá nada. Esto se debe a que el miembro del objeto dinámico Files.file no es el mismo que files.file.
• Todos los miembros de objetos dinámicos de datos tienen una propiedad especial, $value. No puede asignar un valor a esta propiedad. Le permite realizar ciertas acciones con el miembro que no funcionarían de otra manera.
• Los objetos dinámicos de datos 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 a Studio. Están disponibles algunos de los ejemplos de esta página de ayuda en las acciones Snippet del script de ejemplo. Puede abrir la Snippet editor ventana y ejecutar el depurador para ver cómo funciona cada ejemplo.

Miembros del Objeto

Los objetos dinámicos de datos mantienen 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 se encierra entre comillas dobles del lado derecho del signo igual.

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

Los objetos dinámicos de datos le permiten reducir la cantidad de variables que utiliza en un script. El ejemplo anterior muestra la manera en que puede utilizar un único objeto para que contenga tres valores en lugar de crear tres variables únicas.

Los miembros de los objetos dinámicos de datos 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 los objetos dinámicos de datos

Esta sección resume la sintaxis relacionada con el uso de objetos dinámicos de datos en los scripts Studio. Puede obtener más información en las demás 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 directrices 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 de una variable de un script varque contenga una cadena JSON o XML. Si utiliza un 'string', debe estar enteramente 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 utilizar una palabra clave para agregar miembros a un objeto, pero si lo desea puede utilizar ASSIGN.

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 dinámico de datos, utilice la palabra clave DYNAMIC en su código antes del nombre de la variable, luego agréguele atributos. 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 los objetos. Si lo desea, puede usar ASSIGN. 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 utilizar un valor contenido en un objeto dinámico de datos, debe hacer referencia al miembro que contenga el valor. Utilice la siguiente sintaxis:

<dynamicObjectName>.<memberName>

Puede utilizar esto de la misma manera en que lo haría con una variable estándar. Puede hacer referencia a objetos dinámicos de datos en cualquier propiedad de las acciones Studio que acepten una sustitución de variables, así como en los 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" 

$valor de la Propiedad Especial de un Objeto

Los objetos dinámicos de datos 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 usarlo para lo siguiente:

• Utilice una función con un miembro de un objeto. Por ejemplo: beowulfCharacteristics.name.first.$value.length(). Puede obtener más información sobre la ejecución de funciones con objetos en la siguiente sección.
• Copie el valor de una propiedad de un objeto dinámico de datos en una variable normal usando la $value propiedad: x = name.first.$value.

No puede asignar un valor a $value. Es de sólo lectura.

Funciones con los Objetos

Las funciones son bloques de código a las que puede llamar y ejecutar en su script. Las funciones le permiten interactuar con los valores de una variable u objeto. Las funciones pueden modificar los valores o decirle algo sobre ellos. Por ejemplo, existen funciones que pueden cambiar a mayúsculas o minúsculas una variable o el valor de un miembro de un objeto. Hay otras funciones que pueden contar el número de elementos en un arreglo o indicar si un valor es numérico.

En sus scripts, puede usar una serie de funciones con los objetos dinámicos de datos. Sólo puede ejecutar las funciones en los miembros de los objetos, no en los objetos mismos.

Para usar una función con un objeto, use la propiedad de objeto especial $value. Esta propiedad es de solo lectura y no supone 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.

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

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

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

Copiar los valores de un objeto a otro objeto o variable

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

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

La variable en la que copia los datos puede ser un objeto dinámico o una variable Studio estándar. 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 al submiembro de otro objeto dinámico. La función copy() no funciona con submiembros, por lo que necesita definir variables iguales entre sí:

DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.name

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

ASSIGN currentContact = "{beowulfCharacteristics.foe}"

Una alternativa 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 dinámico de datos 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 un objeto dinámico, también cambia el valor 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 igual manera, si cambia el valor de beowulfCharacteristics.name a Sparky, se actualiza automáticamente el valor de currentContact.name 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 valor del otro.

Cree un objeto de datos dinámicos desde 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 alguna variable de un script var que contenga una cadena JSON o datos XML. Si utiliza un 'string', debe estar enteramente en una sola línea. Si 'string' pasa a una segunda línea, provoca 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 de caracteres JSON a una Variable.

Otra opción al trabajar con cadena de caracteres JSON es asignarlas a una variable en vez de un objeto dinámico. Este no es el método preferido de trabajo con cadenas de caracteres JSON. No le brinda la flexibilidad de manejar y trabajar con su código como lo hace tener JSON en los objetos dinámicos. Pero puede haber ocasiones en que sea necesario.

Antes de asignar una cadena de caracteres JSON a una variable, debe reemplazar los caracteres de llaves  ( { ) y comillas dobles ( " ) con caracteres de escape. Puede usar un editor de texto para reemplazar manualmente los caracteres o la función replace() para hacerlo en el script. En la asignación de variables, la cadena de caracteres JSON debe ir precedida de un signo de dólar ( $ ), como se muestra en el siguiente ejemplo. El signo de dólar indica un valor que contiene un carácter 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\"}]}}}}}]}"
		

Cree un Objeto Dinámico de Datos a partir de una Respuesta REST.

Los objetos de datos dinámicos se crean automáticamente a partir de las respuestas de las llamadas a la API REST. Estas respuestas pueden estar en JSON o XML. Studiolos 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 dinámico de datos, DynamicReturn. No necesitas usar la palabra clave DYNAMIC con esta variable, porque el script la convierte en objeto dinámico de datos de forma automática.

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

Preparar los Datos de Carga para las Llamadas a la API REST

Puede preparar los datos de carga para las llamadas a la API REST y enviarlos como JSON usando la función asjson(). El método preferido para esta tarea es utilizar 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, se declara TokenInput como un objeto dinámico con tres miembros, grant_type, usernamey password. Se declara que TokenJsonInput contiene TokenInput en forma de cadena utilizando la función asjson(). En la última línea del ejemplo, se declara que la variable TokenResponse contiene la solicitud REST, que luego se puede usar en el código de script para enviar la solicitud.

Convertir un objeto dinámico de datos a JSON o XML

Puede convertir el contenido de un objeto dinámico a una cadena 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 desee convertir. En Studio, puede hacerlo en uno de dos lugares, ya sea en una acción Snippet o en la propiedad de la acción que necesita del objeto los datos convertidos.

Ambos enfoques funcionan por igual. Sin embargo, la ventaja de crear una variable en un Snippet para contener el objeto convertido es que facilita ver dónde está sucediendo la conversión. No necesita saber qué acción requiere los contenidos convertidos del objeto.

Para convertir un objeto en un Snippet, utilice 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 usó en el Snippet. Del 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, incluidos valores numéricos y booleanos Un tipo de datos que tiene dos valores posibles: verdadero y falso.. Para los valores que no son cadenas, debe analizar manualmente el JSON para eliminar las comillas dobles. Puede hacer esto usando la replace() función.

Manejar caracteres especiales en las Teclas JSON

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

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

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

La segunda y tercera líneas en el ejemplo anterior muestran el objeto dinámico que se está convirtiendo a JSON, posteriormente la replace() función que se usa para reemplazar HYPHENPLACEHOLDER con el carácter de guion.

Ver el contenido de los Objetos Dinámicos

You can view the contents of dynamic objects in the Snippet editor window when you run the debugger. This allows you to verify that the object holds the data it's supposed to at each step in your code.

1. In Studio, double-click on a Snippet action.
2. Add snippet code, if necessary.
3. On the Debugger tab, click the Variables as Tree tab.
4. On the Debugger tab, click the down arrow next to the Start Debugging icon and select Step Into . If you don't want to step through the code line by line, click the Start Debugging icon.
5. Click the Step icon and observe the contents on the Variables as Tree tab. Each time you click Step, this field updates with the variables and objects in the script after the previous line of code. Skip this step if you clicked Start Debugging.
6. When you have stepped through all lines of code or if you clicked Start Debugging, the Variables as Tree tab displays all variables, objects, and their contents at the end of the snippet.

7. You can click the + icon next to any string arrays or dynamic objects in the code to expand them. If the content is another array or object, you can continue to expand the tree to see what each entity contains.

   View image

   

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

Cuando guarde un script, Studio valida toda la información del mismo. Una de las cosas que verifica es que estén declarados en el script todos los objetos dinámicos a los que se hace referencia en el script. Studio requiere la declaración de un objeto para que se validen todos los objetos a los que se hace referencia en el script. Incluso si se declara el objeto en otro script y se pasa al que se está validando, aún causa 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 se hace referencia al objeto. Entre las llaves de la declaración IF, declare el objeto dinámico. Por ejemplo:

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

La segunda opción es agregar al script un SNIPPET 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 en su script. No es necesario conectar esta acción a 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.