Objets de Données Dynamiques

Les objets sont une structure de données qui peut contenir plusieurs valeurs au sein d'une seule variable. Ils sont utiles lorsque vous avez un ensemble de valeurs qui se rapportent toutes à une « chose » dans votre script. Par exemple, vous pourriez avoir un ensemble de données relatives à un contact, comme 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 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 du JSON ou du XML. Ils sont également créés à partir des réponses aux appels API.

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 d'autres utilités également. Par exemple, vous pouvez les utiliser pour :

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

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 de l'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 sur les propriétés. Au moment de l'exécution, ces informations sont examinées et prises en compte. C’est pourquoi le compilateur ne détecte pas les erreurs avec les objets de données dynamiques. Elles provoquent plutôt des exceptions au moment de l'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 dynamiques 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 de code. 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 casse est importante lorsque vous faites référence aux membres d'un objet de données dynamiques. Par exemple, si vous tentiez d'analyser la valeur de beowulfCharacteristics.files.file avec ASSIGN fileContent = "{beowulfcharacteristics.Files.file}", cela ne renverrait rien. C'est parce que le membre d'objet dynamique 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 être inférieurs à 32 Ko. Lors de la conversion d'un objet en JSON ou en 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 des actions Snippet dans le script d’exemple. Vous pouvez ouvrir la fenêtre Snippet editor et exécuter le débogueur pour voir comment fonctionne 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 s’apparente au nom d’une variable au sein de l’objet. Dans l’exemple suivant, les clés sont name, occupation et foe. Chaque clé possède une valeur qui lui est associée, laquelle est placée entre guillemets doubles à 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 un seul objet peut 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 des objets de données dynamiques dans les scripts Studio. Vous trouverez plus de renseignements dans les autres sections de cette page.

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

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

Le <objectName> doit suivre les mêmes directives d’appellation 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 varcontenant une chaîne JSON ou XML. Si vous utilisez une 'string', elle doit être entièrement sur une seule ligne et placée entre guillemets simples.

Cette syntaxe permet d’ajouter des membres à un objet :

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

Les noms de membres sont sensibles à la casse. Vous n’êtes pas obligé 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 Dynamique à l’aide de 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"

Vous n’avez pas besoin d’un mot-clé pour déclarer des membres d’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 façon 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 variable, 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 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 :

• Utiliser une fonction avec un membre d'un objet. Par exemple : beowulfCharacteristics.name.first.$value.length(). Vous pouvez en savoir plus sur l'exécution de fonctions avec des objets dans la section suivante.
• Copier une valeur d'une propriété d'objet de données dynamiques dans une Variable normale à 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 vous 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 casse de la valeur d'une Variable ou d'un membre d'objet. Il existe d'autres fonctions qui peuvent compter le nombre d'éléments dans un tableau ou vous indiquer si une valeur est numérique.

Il existe un certain nombre de Fonctions disponibles que vous pouvez utiliser avec les objets de données dynamiques dans vos scripts. Vous pouvez uniquement exécuter des fonctions sur des membres d'objet, 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'objet : obj.member.$value.function().

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

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

Copier des valeurs d'Objet dans un autre Objet ou une autre Variable

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

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

La variable dans laquelle vous copiez des 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 du 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 définir les variables comme étant égales l’une à l’autre :

DYNAMIC currentContact

currentContact.who = beowulfCharacteristics.name

Vous pouvez copier la valeur du sous-membre d’un objet dynamique dans une variable standard. Cela entraîne automatiquement la conversion de la variable en 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 empêche la variable d’être convertie en objet dynamique. Par exemple :

ASSIGN currentContact = "{beowulfCharacteristics.foe}"

Une solution de rechange à la mise en forme 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 attribuer une référence à un objet de données dynamiques à 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’attribution 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 ou l’autre objet dynamique, la valeur change également dans l’autre objet. Par exemple, si vous remplacez currentContact.name par Beowulf Herot, la valeur de beowulfCharacteristics.name se met automatiquement à jour à Beowulf Herot. De même, si vous remplacez la valeur de beowulfCharacteristics.name par Sparky, la valeur de currentContact.name se met automatiquement à jour à 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. Cela duplique la valeur. Si vous modifiez la valeur de l’un, cela ne modifie pas automatiquement l’autre valeur.

Créer un Objet de Données Dynamiques à 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 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 préciser un 'string' qui contient des données JSON ou XML. Vous pouvez également préciser le nom d’une variable de script var qui contient une chaîne JSON ou des données XML. Si vous utilisez un 'string', il doit se trouver entièrement sur une seule ligne. Si le '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.

Attribuer une chaîne JSON à une variable

Une autre Option lorsque vous travaillez avec des chaînes JSON consiste à les attribuer à une variable plutôt qu’à un objet dynamique. Ce n’est pas la méthode privilégiée pour travailler avec des chaînes JSON. Elle ne vous offre pas la même flexibilité pour gérer et travailler avec votre code que celle offerte par le JSON dans des objets dynamiques. Cependant, il peut arriver que cela soit nécessaire.

Avant de pouvoir attribuer une chaîne JSON à une variable, vous devez remplacer les caractères accolade ( { ) et guillemet ( " ) par des caractères d’échappement. Vous pouvez utiliser un éditeur de texte pour remplacer les caractères manuellement, ou la replace() fonction pour le faire dans le script. Dans l’attribution de la variable, la chaîne JSON doit être précédée d’un signe dollar ( $ ), comme illustré dans l’exemple suivant. Le signe 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’un Response REST

Les objets de données dynamiques sont automatiquement créés à partir des réponses des appels API REST. Ces réponses peuvent être en JSON ou en 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() retourne 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 dynamique qui contient la réponse REST, utilisez ASSIGN fileContent = "{DynamicReturn.files.file}". Cela assigne la valeur extraite ({DynamicReturn.files.file}) à la variable fileContent. Vous pouvez également utiliser ASSIGN fileContent = DynamicReturn.files.file.$value pour analyser la réponse.

Préparer les données de Charge utile pour les appels d'API REST

Vous pouvez préparer des données de charge utile pour les appels d'API REST et les envoyer en JSON à l'aide de la fonction asjson(). La méthode privilégiée pour cette tâche consiste à utiliser l'REST API action. Cependant, vous pouvez également le faire dans un extrait. 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 comportant trois membres, grant_type, username et password. TokenJsonInput est déclaré pour contenir TokenInput sous une forme convertie en 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 demande REST, qui peut ensuite être utilisée dans le code du script pour envoyer la demande.

Convertir un Objet de données Dynamique en JSON ou en XML

Vous pouvez convertir le contenu d'un objet dynamique en une 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 souhaitez convertir. Dans Studio, vous pouvez le faire à l'un des deux endroits suivants, soit dans une Snippet action, soit dans la propriété d'action qui nécessite les 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 une Snippet pour contenir l'objet converti est qu'il devient plus facile de voir où la conversion se produit. Vous n'avez pas besoin de savoir quelle action nécessite le contenu converti de l'objet.

Pour convertir un objet dans une 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 la Snippet. D'après l'exemple de syntaxe, vous configureriez la propriété d'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 doubles. Vous pouvez le faire à l'aide de la fonction replace().

Gérer les Caractères spéciaux dans les Clés JSON

Les caractères spéciaux dans les noms de variable causent 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 contenant la paire clé-valeur CONTENT-TYPE. Dans 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 avoir converti l'objet en 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 l'objet dynamique en cours de conversion en JSON, puis la fonction replace() utilisée pour remplacer HYPHENPLACEHOLDER par le caractère trait d'union.

Afficher le Contenu des Objets Dynamiques

Vous pouvez afficher le contenu des objets de données dynamiques dans l'outil de débogage de l'action SNIPPET.

1. Dans Studio, ouvrez un script contenant une action Snippet.
2. Cliquez sur Ouvrir l’éditeur sur l’action Snippet.

3. Ajoutez du code Snippet, s'il n'en contient pas déjà.

4. Du côté gauche de la fenêtre de l'éditeur de Snippet, cliquez sur l'icône du bogue . Le panneau Exécuter et Déboguer se déploie à partir du côté gauche de la fenêtre.

5. Cliquez sur le triangle pour commencer le débogage.

6. Affichez le contenu de la Section Variables du panneau Exécuter et Déboguer. Cette section montre les variables et leurs valeurs une fois que le débogueur a exécuté tout le code du snippet.
7. Cliquez sur toute variable ayant la valeur {Dynamic} pour l'étendre et afficher les valeurs de ses membres.

Erreur de validation de script et Objets Dynamiques

Lorsque vous enregistrez un script, Studio valide toutes les informations qu'il contient. L'une des choses qu'il vérifie est que tous les objets dynamiques référencés dans le script sont déclarés dans celui-ci. 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 à celui en cours de validation, cela provoque tout de même l'erreur. 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. La première consiste à ajouter une instruction IF avec une variable TEST au snippet 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 un SNIPPET au script qui contient la déclaration d'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 garder les autres actions SNIPPET de votre script bien organisées. Vous n'avez pas besoin de connecter cette action aux 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.