Objets de données dynamiques

Les objets sont une structure de données qui peut contenir plusieurs valeurs dans une seule variable. Ils sont utiles lorsque vous avez une collection de valeurs qui se rapportent toutes à une « chose » dans votre script. Par exemple, vous pouvez disposer d'un ensemble de données relatives à un contact, telles que le nom, le numéro de téléphone et l'adresse e-mail.  Vous pouvez stocker toutes ces valeurs dans un objet. L'avantage de cette méthode est qu'elle permet de réduire le nombre de variables utilisées dans vos scripts.

Studio prend en charge les objets de type DynamicData. Ce type de données peut fonctionner avec des données qui n'ont pas de format ou de type statique, comme XML ou JSON.

Vous pouvez créer des objets de données dynamiques en les déclarant dans le code Snippet ou en analysant JSON ou XML. Ils sont également créés à partir des réponses aux appels d'API et de certaines actions du cadre.

Vous pouvez utiliser un objet de données dynamiques dans n'importe quelle action Studio où vous pouvez utiliser une variable standard. Les objets de données dynamiques peuvent être utilisés pour contenir des données, tout comme les variables standard. Ils ont également d'autres usages. Par exemple, vous pouvez les utiliser pour :

• Générer des appels d'API REST.
• Traiter les réponses de l’action Workflowdata. Cette action renvoie les données de workflow dans un objet de données dynamique.

Informations clés sur les objets de données dynamiques

• Les valeurs détenues par un objet de données dynamiques sont appelées « membres ».
• Chaque membre est identifié par un nom. Par exemple, dans beowulfCharacteristics.occupation, beowulf est l'objet et occupation est le nom d'un de ses membres.
• Le type des membres de l'objet est déterminé au moment de l'exécution. Le compilateur enregistre les informations relatives aux propriétés. Au moment de l'exécution, les informations sont examinées et exploitées. C'est pourquoi le compilateur ne détecte pas les erreurs avec les objets de données dynamiques. Au lieu de cela, les erreurs provoquent des exceptions d'exécution.
• Les objets de données dynamiques peuvent avoir des membres créés dynamiquement. Après avoir déclaré un objet de données dynamique dans votre script, vous affectez des valeurs aux membres de l'objet sur les lignes suivantes. Vous pouvez même attribuer des valeurs aux membres dans d'autres snippets. Si les membres n'existent pas, ils sont automatiquement créés et les valeurs spécifiées leur sont attribuées.
• Les objets de données dynamiques peuvent stocker de nombreux types de données. Les variables Snippet standard sont implicitement typées, ce qui signifie que le type est déterminé lorsque le compilateur Studio compile le code.  Les objets de données dynamiques sont de type DynamicData. Les membres d'un objet sont implicitement typés.
• La sensibilité à la casse est importante lorsqu'il s'agit de référencer les membres d'un objet de données dynamique. Par exemple, si vous tentez d'analyser la valeur de beowulfCharacteristics.files.file avec ASSIGN fileContent = "{beowulfcharacteristics.Files.file}", vous n'obtiendrez rien. En effet, Files.file n'est pas identique à files.file.
• Tous les membres des objets de données dynamiques ont une propriété spéciale, $value. Vous ne pouvez pas attribuer de valeur à cette propriété. Elle vous permet d'effectuer certaines actions avec le membre qui, autrement, ne fonctionneraient pas.
• Les objets de données dynamiques et leurs membres doivent avoir une taille inférieure à 32 Ko. Lors de la conversion d'un objet en JSON ou XML, le contenu résultant doit être inférieur à 32 Ko. Si le contenu d'un objet converti dépasse cette limite, il est tronqué.

Essayez.

Téléchargez le script d’exemples d’objets et importez-le dans Studio. Certains exemples de cette page d'aide sont disponibles dans les actions Snippet de l’exemple de script. Vous pouvez ouvrir la fenêtre Snippet editor et lancer le débogueur pour voir comment fonctionne l'exemple.

Membres de l'objet

Les objets de données dynamiques contiennent leurs propriétés, également appelées « membres », sous la forme de paires clé/valeur. La clé est le nom du membre et est comme le nom d'une variable dans l'objet. Dans l’exemple ci-dessous, les clés sont name, occupation et foe. Chaque clé est associée à une valeur, qui est placée entre guillemets à droite du signe égal.

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

Les objets de données dynamique permettent de réduire le nombre de variables que vous utilisez dans un script. L'exemple précédent montre comment utiliser un seul objet pour contenir trois valeurs au lieu de créer trois variables uniques.

Les membres des objets de données dynamiques peuvent avoir leurs propres ensembles de membres. Ces sous-membres suivent les mêmes règles que les membres de premier niveau. Par exemple :

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" 

Résumé de la syntaxe des objets de données dynamiques

Cette section résume la syntaxe liée à l'utilisation d'objets de données dynamiques dans les scripts Studio. Pour en savoir plus, consultez les autres sections de cette page.

Déclarez un objet de données dynamique en utilisant la syntaxe suivante :

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

Les <objectName> doivent suivre les mêmes conventions de dénomination que les variables standard dans Studio. Les noms d'objets sont sensibles à la casse.

La clause FROM est facultative. Vous pouvez l'utiliser pour créer un objet à partir du contenu d'une chaîne 'string'ou d'une variable de script var qui contient une chaîne JSON ou XML. Si vous utilisez une 'string' , elle doit se trouver entièrement sur une seule ligne et entre guillemets simples.

La syntaxe suivante permet d'ajouter des membres à un objet :

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

Les noms des membres sont sensibles à la casse. Il n'est pas nécessaire d'utiliser un mot-clé pour ajouter des membres à un objet, mais vous pouvez utiliser ASSIGN si vous le voulez.

Créez un tableau dans un objet de données dynamique en utilisant la syntaxe suivante :

DYNAMIC <object>

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

Déclaration d’objets de données dynamiques

Pour déclarer un objet de données dynamique, utilisez le mot-clé DYNAMIC dans votre code avant le nom de la variable, puis ajoutez-y des propriétés. Par exemple :

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

Il n'est pas nécessaire d'utiliser un mot-clé pour déclarer les membres d'un objet. Vous pouvez utiliser ASSIGN si vous le voulez. La référence à un membre crée dynamiquement le membre s'il n'existe pas déjà.

Référence à un membre d'un objet dynamique de données

Lorsque vous devez utiliser une valeur contenue dans un objet de données dynamiques, vous devez vous référer au membre qui contient la valeur. Utilisez la syntaxe suivante :

<dynamicObjectName>.<memberName>

Vous pouvez l'utiliser de la même manière qu'une variable standard. Vous pouvez faire référence à des objets de données dynamiques dans n'importe quelle propriété d'action Studio qui accepte la substitution de variables, ainsi que dans les snippets.

Par exemple, pour faire référence au membre nom de l'objet suivant, vous devez utiliser beowulfCharacteristics.name.

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

Propriété d'objet spéciale $value

Les objets de données dynamiques possèdent une propriété spéciale, $value. Cette propriété vous permet de faire des choses avec des objets et leurs valeurs d'une manière qui ne serait pas possible autrement. Vous pouvez l’utiliser pour :

• Utilisation d’une fonction avec un membre d'un objet. Par exemple : beowulfCharacteristics.name.first.$value.length(). Pour en savoir plus sur l'exécution de fonctions avec des objets, consultez la section suivante.
• Copiez une valeur d'une propriété d'un objet de données dynamique dans une variable ordinaire à l'aide de la propriété $value : x = name.first.$value.

Vous ne pouvez pas attribuer de valeur à $value. Elle est en lecture seule.

Fonctions avec objets

Les fonctions sont des blocs de code qui peuvent être appelés et exécutés dans votre script. Les fonctions permettent d'interagir avec les valeurs d'une variable ou d'un objet. Les fonctions peuvent modifier les valeurs ou vous donner des informations à leur sujet. Par exemple, il existe des fonctions qui peuvent transformer la valeur d'une variable ou d'un membre d'un objet. D'autres fonctions permettent de compter le nombre d'éléments d'un tableau ou de déterminer si une valeur est numérique.

Il existe un certain nombre de fonctions que vous pouvez utiliser avec les objets de données dynamiques dans vos scripts. Vous ne pouvez exécuter des fonctions que sur les membres des objets, et non sur les objets eux-mêmes.

Pour utiliser une fonction avec un objet, utilisez la propriété d'objet spéciale $value. Cette propriété est en lecture seule et n'entraîne pas la création d'une propriété $value dans l'objet. Elle empêche que le nom de la fonction devienne une propriété de l'objet. Elle renvoie la valeur littérale de la chaîne du membre de l'objet avec lequel elle est utilisée.

La syntaxe suivante permet d'exécuter une fonction sur un membre d'un objet : obj.member.$value.function().

Par exemple, pour exécuter la fonction length() sur name.first, vous devez utiliser :

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

Copie des valeurs d'un objet dans un autre objet ou une autre variable

Vous pouvez créer une copie des données d'un objet si vous voulez disposer de deux versions de ces données. Cela vous permet de modifier l'une sans affecter l'autre. Pour ce faire, utilisez la fonction copy() intégrée en suivant la syntaxe suivante :

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

La variable dans laquelle vous copiez les données peut être un objet dynamique ou une variable Studio standard. S'il s'agit d'une variable standard, elle est automatiquement convertie en objet dynamique.

Vous pouvez copier la valeur d'un sous-membre d'un objet dynamique dans le sous-membre d'un autre objet dynamique. La fonction copy() ne fonctionne pas avec les sous-membres. Vous devez donc mettre les variables à égalité :

DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.name

Vous pouvez copier la valeur d'un sous-membre d'un objet dynamique dans une variable standard. Cela entraîne automatiquement la conversion de la variable en un objet dynamique. Pour éviter cela, le nom de l'objet dynamique et du sous-membre que vous copiez doit être placé entre guillemets et accolades. Cela permet d'éviter que la variable ne soit convertie en un objet dynamique. Par exemple :

ASSIGN currentContact = "{beowulfCharacteristics.foe}"

Une alternative au formatage du nom de l'objet consiste à ajouter la propriété $value :

ASSIGN currentContact = beowulfCharacteristics.foe.$value

Attribution d’une référence à une valeur d'un objet à un autre objet ou une autre variable

Vous pouvez attribuer une référence à un objet dynamique à un autre objet dynamique. Par exemple :

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

DYNAMIC currentContact

ASSIGN currentContact = beowulfCharacteristics

Après l'affectation ci-dessus, currentContact et beowulfCharacterics font tous deux référence aux mêmes données physiques. Si vous modifiez la valeur d’un sous-membre dans l’un des objets dynamiques, la valeur change également dans l’autre. Par exemple, si vous remplacez la valeur de currentContact.name par Beowulf Herot, la valeur de beowulfCharacteristics.name devient automatiquement Beowulf Herot. De même, si vous remplacez la valeur de beowulfCharacteristics.name par Sparky, la valeur de currentContact.name devient automatiquement Sparky.

Il n'est pas possible d'attribuer une référence à un sous-membre individuel. Vous pouvez copier la valeur d'un sous-membre d'un objet dynamique à un autre. La valeur est ainsi dupliquée. Si vous modifiez la valeur de l'un d'entre eux, l'autre n'est pas automatiquement modifié.

Créer un objet de données dynamique à partir de JSON ou de XML

Vous pouvez utiliser un objet de données dynamique pour analyser JSON ou XML.

Définissez l’objet de données dynamique et utilisez la commande FROM pour spécifier les données XML ou JSON avec cette syntaxe :

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

Vous pouvez spécifier une 'string' qui contient des données JSON ou XML. Vous pouvez également spécifier le nom d'une variable de script var qui contient une chaîne JSON ou des données XML. Si vous utilisez une 'string', elle doit se trouver entièrement sur une seule ligne. Si la 'string' passe à une deuxième ligne, une erreur se produit.

Par exemple :

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

Les résultats sont les suivants :

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

Si les paires clé-valeur JSON utilisées dans l'exemple précédent étaient contenues dans une variable appelée famousSwords, vous pourriez créer l'objet de données dynamiques comme suit :

DYNAMIC epicMonsterDoom FROM famousSwords

Les résultats sont les mêmes avec les deux méthodes de création de l'objet.

Affectation d’une chaîne JSON à une variable

L’utilisation des chaînes JSON permet également d’affecter ces chaîne à une variable plutôt qu’à un objet dynamique. Ce n’est pas la méthode à privilégier pour travailler avec des chaînes JSON. Elle ne vous offre pas la souplesse que vous apportent les objets dynamiques JSON pour gérer et utiliser votre code. Dans certains cas, elle peut toutefois être nécessaire.

Avant d’affecter une chaîne JSON à une variable, vous devez ajouter un caractère d’échappement aux accolades ( { ) et guillemets droits ( " ). Vous pouvez remplacer les caractères manuellement dans un éditeur de texte ou utiliser la fonction replace() pour le faire dans le script. Dans l’affectation de variable, la chaîne JSON doit être précédée du signe $, comme indiqué dans l’exemple suivant. Ce signe indique que la valeur contient des caractères d’échappement.

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\"}]}}}}}]}"
		

Création d’un objet de données dynamique à partir d’une réponse REST

Les objets de données dynamiques sont automatiquement créés à partir des réponses aux appels de l'API REST. Ces réponses peuvent être au format JSON ou XML. Studio les convertit en objets de données dynamiques dans le script. Par exemple :

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

Dans cet exemple, la fonction MakeRestRequest() renvoie un objet de données dynamique, DynamicReturn. Vous n'avez pas besoin d'utiliser le mot-clé DYNAMIC avec cette variable, car le script en fait automatiquement un objet de données dynamique.

Pour analyser l'objet de données dynamiques qui contient la réponse REST, utilisez ASSIGN fileContent = "{DynamicReturn.files.file}". La valeur extraite ({DynamicReturn.files.file}) est ainsi affectée à la variable fileContent. Vous pouvez également utiliser ASSIGN fileContent = DynamicReturn.files.file.$value pour analyser la réponse.

Préparation des données de charge utile pour les appels à l'API REST

Vous pouvez préparer des données de charge utile pour les appels API REST et les envoyer sous forme de JSON à l'aide de la fonction asjson(). La méthode privilégiée pour cette tâche consiste à utiliser l'action REST API. Toutefois, vous pouvez aussi le faire dans un snippet. Par exemple :

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

Dans cet exemple, TokenInput est déclarée comme un objet dynamique avec trois membres : grant_type, username et password. TokenJsonInput est déclaré afin de contenir TokenInput sous forme de chaîne à l'aide de la fonction asjson(). Dans la dernière ligne de l'exemple, la variable TokenResponse est déclarée pour contenir la requête REST, qui peut ensuite être utilisée dans le code du script pour envoyer la requête.

Conversion d’un objet de données dynamique en JSON ou XML

Vous pouvez convertir le contenu d’un objet dynamique en chaîne JSON ou XML. Cela permet de sérialiser les données de l'objet et de les mettre dans un format qui peut être transmis sur internet.

Pour ce faire, utilisez la fonction asjson() ou asxml() avec l'objet que vous voulez convertir. Dans Studio, vous pouvez le faire à deux endroits, soit dans une action Snippet, soit dans la propriété de l’action qui a besoin des données converties de l’objet.

Les deux approches fonctionnent de la même manière. Toutefois, la création d’une variable dans Snippet pour contenir l'objet converti offre l’avantage qu'il est plus facile de voir où la conversion a lieu. Il n'est pas nécessaire de savoir quelle action nécessite le contenu converti de l'objet.

Pour convertir un objet en Snippet, utilisez la syntaxe suivante :

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

Dans la propriété de l'action Studio où vous avez besoin des données JSON ou XML, employez le nom de la variable que vous avez utilisée dans l'action Snippet. D'après l'exemple de syntaxe, vous devez configurer la propriété de l’action avec varJSON.

Pour convertir un objet dans la propriété d’action, configurez la propriété d’action avec le nom de l’objet et la fonction asjson() ou asxml() entre accolades. Par exemple : {myDynamic.asjson()}.

Tous les membres d'un objet dynamique sont traités comme des valeurs de chaîne, y compris les valeurs numériques et booléennes Un type de données qui a deux valeurs possibles : true et false.. Pour les valeurs qui ne sont pas des chaînes, vous devez analyser manuellement le JSON afin de supprimer les guillemets. Vous pouvez faire ceci à l’aide de la fonction replace().

Traitement des caractères spéciaux dans les clés JSON

L’utilisation de caractères spéciaux dans les noms de variables provoque des erreurs dans Studio. Si le JSON que vous utilisez contient des noms de clés avec des caractères spéciaux, vous devez contourner cette limitation. Par exemple, vous pouvez rencontrer des problèmes si vous utilisez des en-têtes contenant la paire clé-valeur CONTENT-TYPE. Dans le cas d’un objet dynamique, un membre d’objet tel que requestPayload.HEADERS.CONTENT-TYPE = "APPLICATION/JSON" provoquerait une erreur.

Une solution consiste à remplacer le caractère spécial par du texte dans l’objet dynamique. Après conversion de l’objet en JSON, remplacez ce texte par le caractère spécial approprié. L’exemple suivant montre un membre d’objet dynamique contenant une clé CONTENT-TYPE, où le texte HYPHENPLACEHOLDER a été utilisé à la place du tiret (-) :

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

Sur la deuxième et la troisième lignes de l’exemple précédent, l’objet dynamique est converti en JSON, puis la fonction replace() est utilisée pour remplacer HYPHENPLACEHOLDER par le tiret.

Consultation du contenu d’objets dynamiques

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

   

Erreur de validation de script et objets dynamiques

Lorsque vous enregistrez un script, Studio valide toutes les informations qu'il contient. Il vérifie notamment que tous les objets dynamiques référencés dans le script sont déclarés dans celui-ci. Studio nécessite une déclaration d'objet pour tous les objets référencés dans le script en cours de validation. Même si l'objet est déclaré dans un autre script et passé dans celui qui est validé, l'erreur se produit toujours. Si vous avez un objet non déclaré dans votre script, vous obtenez une erreur "Function '[name]' has not been defined" lorsque vous enregistrez.

Vous pouvez éviter cette situation de deux façons. Une option consiste à ajouter une instruction IF avec une variable TEST dans le snippet où vous faites référence à l'objet. Dans les accolades de l'instruction IF, déclarez l'objet dynamique. Par exemple :

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

La deuxième option consiste à ajouter au script une page SNIPPET qui contient l'instruction de l'objet et rien d'autre. Si plusieurs objets sont transmis au script, vous pouvez les déclarer tous dans une seule SNIPPET. Cela permet de ne pas encombrer les autres actions SNIPPET de votre script. Il n'est pas nécessaire de relier cette action à d'autres actions du script. Son existence dans le script suffit à satisfaire les besoins du script en matière de déclarations d'objets lors de la validation.