Dynamische gegevensobjecten

Objecten vormen een gegevensstructuur die meerdere waarden kan bevatten binnen een enkele variabele. Ze zijn nuttig wanneer u een verzameling van waarden hebt die allemaal verwant zijn met een "ding" in uw script. U kunt bijvoorbeeld een set gegevens hebben die betrekking hebben tot een contact, zoals de naam, het telefoonnummer en e-mailadres.  U kunt al deze waarden opslaan in een object. Het voordeel hiervan is, dat het aantal variabelen dat kan worden gebruikt in uw scripts, kan verminderen.

Studio Ondersteunt objecten van het type Dynamische gegevens. Dit type kan werken met gegevens die geen statische indeling of type hebben, zoals XML of JSON.

U kunt dynamische gegevensobjecten maken door ze te declareren in Snippet-code of door JSON of XML te parseren. Ze worden ook gemaakt van antwoorden van API-oproepen en bepaalde Framework-acties.

U kunt een dynamisch gegevensobject gebruiken in elke Studio-actie waar u een standaard variabele kunt gebruiken. Dynamische gegevensobjecten kunnen worden gebruikt om gegevens te bevatten, net als standaard variabelen. Ze hebben ook andere toepassingen. U kunt ze bijvoorbeeld gebruiken voor het volgende:

• REST API-aanroepen genereren.
• Behandel de reacties van de Workflowdata -actie. Deze actie retourneert workflowgegevens in een dynamisch gegevensobject.

Belangrijke feiten over dynamische gegevensobjecten

• De waarden die een dynamisch gegevensobject bevat, worden leden genoemd.
• Elk lid wordt geïdentificeerd door een naam. Bijvoorbeeld in beowulfCharacteristics.occupation, is beowulf het object en is occupation de naam van een van de leden.
• Het type van de leden van het object wordt vastgesteld tijdens runtime. De compiler slaat de informatie over de eigenschappen op. Bij runtime wordt de informatie onderzocht en wordt erop gereageerd. Hierdoor kan de compiler fouten met dynamische gegevensobjecten niet vaststellen. In plaats daarvan veroorzaken fouten runtime-uitzonderingen.
• Dynamische gegevensobjecten kunnen dynamisch gemaakte leden hebben. Na het declareren van een dynamische gegevensobject in uw script, wijst u waarden toe aan leden van het object op onderliggende regels. U kunt zelfs waarden toewijzen aan leden in andere snippets. Als de leden niet bestaan, worden ze automatisch aangemaakt en worden de opgegeven waarden eraan toegewezen.
• Dynamische gegevensobjecten kunnen veel gegevenstypes opslaan. Standaard Snippet-variabelen krijgen impliciet een type, wat betekent dat het type wordt bepaald wanneer de Studio-compiler de code compileert.  Dynamische gegevensobjecten zijn van het type DynamicData. De leden van een object worden impliciet getypt.
• Hoofdlettergevoeligheid is belangrijk wanneer u verwijst naar de leden van een dynamisch gegevensobject. Als u bijvoorbeeld probeert de waarde van beowulfCharacteristics.files.file te parseren met ASSIGN fileContent = "{beowulfcharacteristics.Files.file}", levert dit niets op. Dit komt doordat het lid van het dynamisch object Files.file niet hetzelfde is als files.file.
• Alle leden van dynamische gegevensobjecten hebben een speciale eigenschap, $value. U kunt geen waarde toewijzen aan deze eigenschap. Hiermee kunt u bepaalde acties uitvoeren met het lid die anders niet zouden werken.
• Dynamische gegevensobjecten en hun leden moeten kleiner zijn dan 32 KB. Wanneer u een object converteert naar JSON of XML, moet de resulterende inhoud kleiner zijn dan 32 KB. Als de inhoud van een geconverteerd object die limiet overschrijdt, wordt deze afgekapt.

Probeer het

Download het script Objectvoorbeelden en importeer deze in Studio. Sommige van de voorbeelden van deze helppagina zijn beschikbaar in Snippet-acties in het voorbeeldscript. U kunt het Snippet editor venster openen en de debugger uitvoeren om te zien hoe elk voorbeeld werkt.

Objectleden

Dynamische gegevensobjecten houden hun eigenschappen, ook leden genoemd, vast in de vorm van sleutel-/waardeparen. De sleutel is de naam van het lid en is zoals de naam van een variabele binnen het object. In het volgende voorbeeld zijn de sleutels name, occupation en foe. Aan elke sleutel is een waarde gekoppeld die rechts van het gelijkheidsteken tussen dubbele aanhalingstekens staat.c

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

Met dynamische gegevensobjecten kunt u het aantal variabelen dat u in een script gebruikt, verminderen. Het voorgaande voorbeeld toont u hoe u één object kunt gebruiken om drie waarden te behouden in plaats van drie unieke variabelen te maken.

De leden van dynamische gegevensobjecten kunnen hun eigen set leden hebben. Deze subleden volgen dezelfde regels als leden op het eerste niveau. Bijvoorbeeld:

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" 

Syntaxisoverzicht dynamisch gegevensobject

Deze sectie geeft een overzicht van de syntax met betrekking tot het gebruik van dynamische gegevensobjecten in Studio-scripts. In de andere secties op deze pagina vindt u meer informatie.

Een dynamisch gegevensobject declareren met deze syntaxis:

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

De <objectName> moet dezelfde naamgevingsrichtlijnen volgens als de standaardvariabelen in Studio. Objectnamen zijn hoofdlettergevoelig.

De FROM-clausule is optioneel. U kunt deze gebruiken om een object te maken van de inhoud van een string 'string'of een scriptvariabele vardie een JSON- of XML-string bevat. Als u een 'string' gebruikt, moet dit volledig op één regel staan en tussen enkele aanhalingstekens staan.

Leden aan een object toevoegen met deze syntaxis:

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

Namen van leden zijn hoofdlettergevoelig. U hoeft geen trefwoord te gebruiken om leden toe te voegen aan een object, maar als u dat wenst, kunt u ASSIGN gebruiken.

Een array in een dynamisch gegevensobject maken met deze syntaxis:

DYNAMIC <object>

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

Dynamische gegevensobjecten declareren

Om een dynamisch gegevensobject te declareren, gebruikt u het trefwoord DYNAMIC in uw code vóór de naam van de variabele. Voeg daarna de eigenschappen toe. Bijvoorbeeld:

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

U hebt geen trefwoord nodig om objectleden te declareren. Als u dat wilt, kunt u ASSIGN gebruiken Als u dynamisch verwijst naar een lid, wordt dit lid gemaakt als het nog niet bestaat.

Verwijzen naar een lid van een dynamisch gegevensobject

Als u een waarde moet gebruiken die een dynamisch gegevensobject bevat, moet u verwijzen naar het lid dat de waarde bevat. Gebruik de volgende syntaxis:

<dynamicObjectName>.<memberName>

U kunt dit op dezelfde manier gebruiken als een standaard variabele. U kunt verwijzen naar dynamische gegevensobjecten in elke Studio-actie-eigenschap die het vervangen van een variabele accepteert, evenals in snippets.

Om bijvoorbeeld te verwijzen naar het naamlid van het volgende object, zou u beowulfCharacteristics.name gebruiken.

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

Speciale objecteigenschap $value

Dynamische gegevensobjecten hebben een speciale eigenschap, $value. Met deze eigenschap kunt u dingen doen met objecten en hun waarden op een manier die anders niet zou mogelijk zijn. U kunt deze gebruiken voor het volgende:

• Gebruik een functie met een lid van een object. Bijvoorbeeld: beowulfCharacteristics.name.first.$value.length(). U kunt meer leren over lopende functies met objecten in de volgende sectie.
• Kopieer een waarde van de eigenschap van een dynamische gegevensobject in een gewone variabele met de $value eigenschap: x = name.first.$value.

U kunt geen waarde toewijzen aan $value. Dit is alleen-lezen.

Functies met objecten

Functies zijn blokken van code die kunnen worden opgeroepen en uitgevoerd in uw script. Functies bieden u de mogelijkheid interactief te werken met de waarden in een variabele of object. Functies kunnen waarden wijzigen of u iets vertellen erover. Er zijn bijvoorbeeld functies die de case of de waarde van het objectlid kunnen transformeren. Er zijn andere functies die het aantal elementen in een array kunnen tellen of u laten weten of een waarde numeriek is.

Er zijn een aantal functies beschikbaar die u kunt gebruiken met de dynamische gegevensobjecten in uw scripts. U kunt functies alleen uitvoeren op objectleden, niet op de objecten zelf.

Om een functie te gebruiken met een object, moet u de speciale objecteigenschap $value gebruiken. Deze eigenschap is alleen-lezen en resulteert niet in een $value-eigenschap die wordt gemaakt in het object. Dit voorkomt dat de naam van de functie tot een eigendom van het object wordt gemaakt. Dit retourneert de letterlijke stringwaarde van het objectlid waarmee het wordt gebruikt.

Gebruik de volgende syntax om een functie uit te voeren op een objectlid: obj.member.$value.function().

Om bijvoorbeeld de length()-functie uit te voeren op name.first, zou u het volgende gebruiken:

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

Objectwaarden kopiëren naar een ander object of variabele

U kunt een kopie maken van de gegevens die een object bevatten als u twee versies van de gegevens wilt. Hiermee kunt u de ene wijzigen zonder de andere te beïnvloeden. Gebruik hiervoor de ingebouwde copy() functie volgens deze syntaxis:

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

De variabele waarin u gegevens kopieert, kan een dynamisch object of een standaard Studio variabele zijn. Als dit een standaard variabele is, wordt deze automatisch geconverteerd naar een dynamisch object.

U kunt de waarde van een sublid van een dynamisch object kopiëren in het sublid van een ander dynamisch object. De copy()-functie werkt niet met subleden. U moet de variabelen dus gelijk aan elkaar instellen.

DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.name

U kunt de waarde van een sublid van een dynamisch object kopiëren in een standaard variabele. Hierdoor wordt de variabele automatisch geconverteerd naar een dynamisch object. Om dit te voorkomen, moet de naam van het dynamisch object en het sublid dat u kopieert, tussen dubbele aanhalingstekens en accolades staan. Dit verhindert dat de variabele wordt geconverteerd naar een dynamisch object. Bijvoorbeeld:

ASSIGN currentContact = "{beowulfCharacteristics.foe}"

Een alternatief voor het opmaken van de naam van het object, is het toevoegen van de $value-eigenschap:

ASSIGN currentContact = beowulfCharacteristics.foe.$value

Een referentie naar een objectwaarde toewijzen aan een ander object of een andere variabele

U kunt een referentie naar een dynamisch gegevensobject toewijzen aan een ander dynamisch object. Bijvoorbeeld:

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

DYNAMIC currentContact

ASSIGN currentContact = beowulfCharacteristics

Na de bovenstaande toewijzing, verwijzen currentContact en beowulfCharacterics beide naar dezelfde fysieke gegevens. Als u de waarde van een sublid wijzigt in een dynamisch object, verandert de waarde ook in het andere object. Als u bijvoorbeeld currentContact.name wijzigt naar Beowulf Herot, wordt de waarde van beowulfCharacteristics.name automatisch bijgewerkt naar Beowulf Herot. Als u de waarde van beowulfCharacteristics.name wijzigt naar Sparky, wordt de waarde van currentContact.name op dezelfde manier automatisch bijgewerkt naar Sparky.

U kunt geen referentie toewijzen aan een individueel sublid. U kunt de waarde van een sublid kopiëren van het ene dynamisch object naar een ander. Dit dupliceert de waarde. Als u de ene waarde wijzigt, wordt de andere waarde niet automatisch gewijzigd.

Een dynamisch gegevensobject maken op basis van JSON of XML

U kunt een dynamisch gegevensobject gebruiken om JSON of XML te parseren.

Definieer het dynamische gegevensobject en gebruik de FROM-instructie om JSON- of XML-gegevens op te geven met deze syntax:

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

U kunt een 'string' doorgeven die de JSON- of XML-gegevens bevat. U kunt ook de naam van een scriptvariabele var opgeven die een JSON-string of XML-gegevens bevat. Als u een 'string' gebruikt, moet dit volledig op één regel staan. Als de 'string' splitst naar een tweede regel, veroorzaakt dit een fout.

Bijvoorbeeld:

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

De resultaten hiervan zijn :

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

Als de JSON sleutelwaardeparen die worden gebruikt in het voorgaande voorbeeld, waren opgenomen in een variabele met de naam famousSwords, kunt u in plaats daarvan het dynamische gegevensobject als volgt maken:

DYNAMIC epicMonsterDoom FROM famousSwords

De resultaten zijn dezelfde met beide methoden voor het maken van het object.

Wijs een JSON-string toe aan een variabele

Een andere optie wanneer u werkt met JSON-strings, is ze toe te wijzen aan een variabele in plaats van een dynamisch object. Dit is niet de voorkeursmethode van werken met JSON-strings. Het geeft u niet de flexibiliteit van het beheren van en werken met uw code zoals JSON in dynamische objecten doet. Dit kan echter soms wel nodig zijn.

Voordat u een JSON-string toewijst aan een variabele, moet u de accolade  ( { ) en het dubbele aanhalingstekens ( " ) vervangen door escape-tekens. U kunt een teksteditor gebruiken om de tekens handmatig te vervangen of u kunt de replace() functie gebruiken om dit in het script te doen. In de variabelentoewijzing, moet de JSON-string een dollarteken ( $ ) hebben als prefix, zoals weergegeven in het volgende voorbeeld. Het dollarteken geeft een waarde aan die escape-tekens bevat.

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

Een dynamisch gegevensobject maken op basis van een REST-antwoord

Dynamische gegevensobjecten worden automatisch gemaakt op basis van antwoorden van REST API-aanroepen. Deze antwoorden kunnen in JSON of XML zijn. Studio converteert ze naar dynamische gegevensobjecten in het script. Bijvoorbeeld:

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

In dit voorbeeld retourneert de functie MakeRestRequest() een dynamisch gegevensobject DynamicReturn. U hoeft het trefwoord DYNAMIC niet te gebruiken bij deze variabele omdat het script er automatisch een dynamisch gegevensobject van maakt.

Om het dynamische gegevensobject met de REST-respons te parseren, gebruikt u ASSIGN fileContent = "{DynamicReturn.files.file}". Hiermee wordt de geëxtraheerde waarde ({DynamicReturn.files.file}) toegewezen aan de variabele fileContent. U kunt ook ASSIGN fileContent = DynamicReturn.files.file.$value om de respons te parseren.

Payloadgegevens voor REST API-aanroepen voorbereiden

U kunt payloadgegevens voor REST API-aanroepen voorbereiden en ze als JSON verzenden met behulp van de asjson()-functie. De voorkeursmethode voor deze taak is het gebruik van de REST API -actie. U kunt dit echter ook bereiken in een snippet. Bijvoorbeeld:

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

In dit voorbeeld wordt TokenInput gedeclareerd als een dynamische object met drie leden, grant_type, username en password. TokenJsonInput wordt gedeclareerd om TokenInput in stringvorm te bevatten met behulp van de asjson()-functie. In de laatste regel van het voorbeeld wordt de variabele TokenResponse gedeclareerd om het REST-verzoek te bevatten, die vervolgens in de scriptcode kan worden gebruikt om het verzoek te verzenden.

Een dynamisch gegevensobject converteren naar JSON of XML

U kunt de inhoud van een dynamisch object converteren naar een JSON- of XML-string. Dit serialiseert de gegevens in het object en zet het in een formaat dan kan worden verzonden via internet.

Gebruik hiervoor de functie asjson() of asxml() met het object dat u wilt converteren. In Studio kunt u dat doen op een van twee plaatsen, hetzij in een Snippet -actie of in de actie-eigenschap die de geconverteerde gegevens van het object vereist.

Beide benaderen het werk op dezelfde manier. Het maken van een variabele in een Snippet voor het geconverteerde object heeft echter het voordeel dat het eenvoudiger zichtbaar is waar het converteren plaatsvindt. U hoeft niet te weten welke actie de geconverteerde inhoud van het object vereist.

Om een object te converteren in Snippet, gebruikt u de volgende syntax:

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

In de eigenschap van de Studio-actie waar u de JSON- of XML-gegevens nodig hebt, gebruik u de naam van de variabele die u hebt gebruikt in de Snippet. Vanaf het syntaxvoorbeeld, kunt u de actie-eigenschap configureren met varJSON.

Om een object in de actie-eigenschap te converteren, configureert u de actie-eigenschap met de naam van het object en de asjson() of asxml() -functie tussen accolades. Bijvoorbeeld: {myDynamic.asjson()}

Alle leden van een dynamisch object worden behandeld als stringwaarden, inclusief numerieke en Boolean Een gegevenstype dat twee mogelijke waarden heeft: Waar en Onwaar. waarden. Voor waarden die geen strings zijn, moet u de JSON handmatig parseren om de dubbele aanhalingstekens te verwijderen. U kunt dit doen met de replace() -functie.

Speciale tekens behandelen in JSON-sleutels

Speciale tekens in variabele namen veroorzaken fouten in Studio. Als de JSON waarmee u werkt sleutels heeft met speciale tekens in de naam, moet u deze beperking omzeilen. Dit kan bijvoorbeeld een probleem zijn wanneer u werkt met kopteksten die het CONTENT-TYPE-sleutelwaardepaar bevatten. Wanneer u in een dynamisch object werkt, zal een objectlid, zoals requestPayload.HEADERS.CONTENT-TYPE = "APPLICATION/JSON" een fout veroorzaken.

Een oplossing is het vervangen van het speciale teken met tekst in het dynamisch object. Na het converteren van het object naar JSON, vervangt u de tekst door het correcte speciale teken. Het volgende voorbeeld toont een dynamisch objectlid dat een CONTENT-TYPE-sleutel bevat waar de tekst HYPHENPLACEHOLDER werd gebruikt in plaats van het koppelteken ( - ):

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

De tweede en derde lijnen in het voorgaande voorbeeld tonen het dynamisch object dat wordt geconverteerd naar JSON en dan de replace() functie die wordt gebruikt om HYPHENPLACEHOLDER te vervangen door het koppelteken.

Inhoud van dynamische objecten weergeven

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

   

Scriptvalidatiefout en dynamische objecten

Wanneer u een script opslaat, valideert Studio alle informatie erin. Een van de zaken waarop wordt gecontroleerd, is dat alle dynamische objecten waarnaar wordt verwezen in het script, worden gedeclareerd in het script.e Studio vereist dat een objectdeclaratie voor alle objecten waarnaar wordt verwezen in het script, wordt gevalideerd. Zelfs als het object is gedeclareerd in een ander script en is doorgegeven in het scrip dat wordt gevalideerd, veroorzaakt nog steeds de fout. Als u een niet-gedeclareerd object hebt in uw script, ziet u een fout "Functie '[name]' is niet gedefinieerd" wanneer u opslaat.

Er zijn twee manieren waarop u dit kunt voorkomen. Eén optie is het toevoegen van een IF-verklaring met een TEST variabele voor de snippert waar u verwijst naar het object. Declareer het dynamisch object tussen de accolades van de IF-verklaring. Bijvoorbeeld:

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

De tweede optie is het toevoegen van een SNIPPET aan het script dat de objectdeclaratie bevat en niets anders. Als er meerdere objecten worden doorgegeven in het script, moet u ze allemaal declareren in één SNIPPET. Dit is nuttig om de overige SNIPPET-acties in uw script, geordend te houden. U hoeft deze actie niet te verbinden met andere acties in het script. Het bestaan ervan in het script volstaat om te voldoen aan behoefte van het script voor objectdeclaraties tijdens de validatie.