Objet 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 courriel.  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 Bout de code ou par analyse syntaxique 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 du flux de travail dans un objet de données dynamique.

Faits saillants 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, beowulfCharacteristics 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 attribuez des valeurs aux membres de l’objet sur les lignes suivantes. Vous pouvez même attribuer des valeurs aux membres dans d’autres extraits. 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 standard Extrait de code sont implicitement typées, ce qui signifie que le type est déterminé lorsque 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 essayez d’analyser la valeur de beowulfCharacteristics.files.file avec ASSIGN fileContent = "{beowulfcharacteristics.Files.file}", vous n’obtiendrez rien. En effet, le membre de l’objet dynamique Files.file n’est pas le même que 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-le

Téléchargez le script d’exemples d’objets et importez-le dans Studio. Certains des exemples de cette page d’aide sont disponibles dans les actions Snippet de l’exemple de script. Vous pouvez ouvrir la Snippet editor fenêtre et lancer le débogueur pour voir le fonctionnement de chaque 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 similaire au nom d’une variable dans l’objet. Dans l’exemple suivant, 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 dynamiques permettent de réduire le nombre de variables utilisées 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 relative à 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 cette syntaxe :

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

<objectName> doit suivre les mêmes conventions de nom 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 être entièrement sur une seule ligne et entre guillemets simples.

Cette syntaxe 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 souhaitez.

Créez un tableau dans un objet de données dynamiques en utilisant cette syntaxe :

DYNAMIC <object>

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

Déclarer des Objets de données dynamiques

Pour déclarer un objet de données dynamiques, utilisez le mot-clé DYNAMIC dans votre code avant le nom de la variable, puis ajoutez-lui 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 souhaitez. La référence à un membre crée dynamiquement le membre s’il n’existe pas déjà.

Référencer 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 référencer le 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 référencer 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 extraits de code.

Par exemple, pour faire référence au membre Nom de l’objet suivant, vous utiliserez 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 ont 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 :

• Utiliser 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.
• Copier une valeur d’une propriété d’un objet de données dynamiques dans une variable ordinaire à l’aide de la propriété $value : x = name.first.$value.

Il n’est pas possible d’attribuer une 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 il est utilisé.

Utilisez la syntaxe suivante pour 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().

Copier les 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 souhaitez 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

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

Vous pouvez affecter 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 est également modifiée dans l’autre objet. Par exemple, si vous remplacez currentContact.name par Beowulf Herot, la valeur de beowulfCharacteristics.name est automatiquement mise à jour pour afficher Beowulf Herot. De même, si vous remplacez la valeur de beowulfCharacteristics.name par Sparky, la valeur de currentContact.name est automatiquement mise à jour pour afficher 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 dynamiques à partir de JSON ou XML

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

Définissez l’objet de données dynamiques et utilisez la commande FROM pour spécifier les données JSON ou XML 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 être entièrement sur une seule ligne. Si 'string' passe à une deuxième ligne, cela provoque une erreur.

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.

Assigner une chaîne JSON à une variable

Une autre option pour travailler avec des chaînes JSON est de les assigner à une variable plutôt qu’à un objet dynamique. Ce n’est pas la méthode préférée pour travailler avec des chaînes JSON. Elle ne vous offre pas la flexibilité de gérer et de travailler avec votre code, comme le fait d’avoir du code JSON dans des objets dynamiques. Cependant, dans certains cas, cela peut s’avérer nécessaire.

Avant d’assigner une chaîne JSON à une variable, vous devez remplacer les accolades ( { ) et les guillemets ( " ) par des caractères d’échappement. Vous pouvez utiliser un éditeur de texte pour remplacer les caractères manuellement ou la fonction replace() pour le faire dans le script. Dans l’assignation de la variable, la chaîne JSON doit être préfixée par un symbole de dollar ($), comme le montre l’exemple suivant. Le symbole du dollar indique une valeur qui 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éer un objet de données dynamiques à partir d’une réponse REST

Les objets de données dynamiques sont automatiquement créés à partir des réponses des appels d’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 dynamiques, DynamicReturn. Il n’est pas nécessaire 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éparer les données utiles pour les appels à l’API REST

Vous pouvez préparer les données utiles pour les appels à l’API REST et les envoyer sous forme de JSON à l’aide de la fonction asjson(). La méthode préférée pour cette tâche est d’utiliser l’action REST API. Cependant, vous pouvez aussi le faire dans un extrait de code. 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é comme un objet dynamique avec trois membres, grant_type, username et password. TokenJsonInput est déclaré pour 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.

Convertir 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 à 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. Cependant, l’avantage de créer une variable dans Snippet pour contenir l’objet converti est 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 dans 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, utilisez 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é 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 (vrai) et false (faux).. Pour les valeurs qui ne sont pas des chaînes, vous devez analyser manuellement le JSON pour supprimer les guillemets. Vous pouvez le faire en utilisant la fonction replace().

Gérer les caractères spéciaux dans les clés JSON

Les caractères spéciaux dans les noms de variables provoquent des erreurs dans Studio. Si le JSON avec lequel vous travaillez contient des clés dont le nom comporte des caractères spéciaux, vous devez contourner cette limitation. Par exemple, cela peut poser un problème lorsque vous travaillez avec des en-têtes qui contiennent la paire clé-valeur CONTENT-TYPE. Dans un objet dynamique, un membre de l’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 avoir converti l’objet au format JSON, remplacez le texte par le caractère spécial correct. L’exemple suivant montre un membre d’objet dynamique qui contient une clé CONTENT-TYPE où le texte HYPHENPLACEHOLDER a été utilisé à la place du trait d’union ( - ) :

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

Les deuxième et troisième lignes de l’exemple précédent montrent que l’objet dynamique est converti au format JSON, puis que la fonction replace() est utilisée pour remplacer HYPHENPLACEHOLDER par le trait d’union.

Afficher le contenu des 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 le script. Studio exige 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 transmis dans celui qui est validé, l’erreur se produit toujours. Si votre script contient un objet non déclaré, vous obtenez une erreur « La fonction « [name] » n’a pas été définie » lors de l’enregistrement.

Il y a deux façons d’éviter cela. Une option consiste à ajouter une instruction IF avec une variable TEST à l’extrait où vous référencez 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 un SNIPPET qui contient la déclaration de l’objet et rien d’autre. Si plusieurs objets sont transmis au script, vous pouvez tous les déclarer dans un seul 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.