Bei einem Objekt handelt es sich um eine Datenstruktur, die mehrere Werte innerhalb einer einzelnen Variablen enthalten kann. Sie sind praktisch, wenn sich mehrere Werte auf ein bestimmtes Element in Ihrem Skript beziehen. Ein Beispiel ist ein Satz mit Daten zu einem bestimmten Kontakt, wie Name, Telefonnummer und E-Mail-Adresse. Sie können alle diese Werte in einem Objekt speichern. Dies bietet den Vorteil, dass Sie die Anzahl der im Skript verwendeten Variablen verringern können.
Studio unterstützt Objekte mit dem DynamicData-Typ. Dieser Typ eignet sich für Daten, die kein statisches Format oder keinen statischen Typ aufweisen, wie XML oder JSON.
Sie können dynamische Datenobjekte durch Deklarieren im Snippet-Code oder durch Parsen von JSON oder XML erstellen. Sie werden auch über Antworten von API-Aufrufen und über bestimmte Framework-Aktionen erstellt.
Dynamische Datenobjekte können in jeder Studio-Aktion verwendet werden, in der auch eine Standardvariable verwendet werden kann. Genau wie Standardvariablen können dynamische Datenobjekte Daten enthalten. Sie haben aber auch noch weitere Verwendungszwecke. Sie können sie beispielsweise folgendermaßen verwenden:
- Generieren Sie REST-API-Aufrufe.
- Verarbeiten Sie die Antworten von der Workflowdata-Aktion. Diese Aktion gibt Arbeitsablaufdaten in einem dynamischen Datenobjekt zurück.
Die Anzahl der dynamischen Datenvariablen und Objekte in einem Skript kann die Ablaufverfolgungbeeinflussen. Bei Skripten, die eine große Anzahl dynamischer Variablen enthalten, können Leistungsprobleme auftreten. Je mehr Daten sie enthalten, desto länger kann es dauern, jede Aktion zu bearbeiten.
Wichtige Fakten über dynamische Datenobjekte
- Die Werte, die ein dynamisches Datenobjekt enthält, werden als Mitglieder bezeichnet.
- Jedes Mitglied wird anhand seines Namens identifiziert. Beispiel: In
- Der Typ der Mitglieder des Objekts wird zur Laufzeit bestimmt. Der Compiler speichert die Informationen über die Eigenschaften. Zur Laufzeit werden die Informationen analysiert und entsprechend umgesetzt. Deshalb erkennt der Compiler keine Fehler, die möglicherweise bei dynamischen Datenobjekten vorliegen. Stattdessen verursachen Fehler zur Laufzeit Ausnahmen.
- Dynamische Datenobjekte können Mitglieder enthalten, die dynamisch erstellt werden. Nachdem Sie ein dynamisches Datenobjekt in Ihrem Skript deklariert haben, weisen Sie den Mitgliedern des Objekts auf den folgenden Zeilen Werte zu. Sie können sogar Mitgliedern in anderen Snippets Werte zuweisen. Wenn die Mitglieder nicht existieren, werden sie automatisch erstellt und die angegebenen Werte werden ihnen zugewiesen.
- Dynamische Datenobjekte können viele verschiedene Datentypen enthalten. Standardmäßige Snippet-Variablen erhalten ihren Typ implizit. Dies bedeutet, dass der Typ bestimmt wird, wenn der Studio-Compiler den Code kompiliert. Dynamische Datenobjekte haben den Typ "DynamicData". Der Typ für die Mitglieder eines Objekts wird implizit angegeben.
- Beim Verweisen auf die Mitglieder eines dynamischen Datenobjekts muss die Groß- oder Kleinschreibung beachtet werden. Beispiel: Wenn Sie versuchen, den Wert von beowulfCharacteristics.files.file mit ASSIGN fileContent = "{beowulfcharacteristics.Files.file}" zu parsen, wird nichts zurückgegeben. Grund hierfür ist, dass das Mitglied
- Alle Mitglieder von dynamischen Datenobjekten verfügen über die spezielle Eigenschaft
- Dynamische Datenobjekte und ihre Mitglieder müssen kleiner als 32 KB sein. Wenn ein Objekt in das JSON- oder XML-Format konvertiert wird, muss der resultierende Inhalt kleiner als 32 KB sein. Übersteigt der Inhalt des konvertierten Objekts dieses Limit, wird er gekürzt.
Testen
Laden Sie das Skript mit Objektbeispielen herunter und importieren Sie es in Studio. Einige der auf dieser Hilfeseite genannten Beispiele sind in
Objektmitglieder
Die in dynamischen Datenobjekten enthaltenen Eigenschaften, auch Mitglieder genannt, werden in Form von Schlüssel-Wert-Paaren gespeichert. Der Schlüssel ist der Name des Mitglieds und entspricht dem Namen einer Variablen innerhalb des Objekts. Im folgenden Beispiel sind name, occupation und foe die Schlüssel. Jedem Schlüssel ist ein Wert zugewiesen, der in doppelte Anführungszeichen eingeschlossen ist und sich rechts neben dem Gleichheitszeichen befindet.
DYNAMIC beowulfCharacteristics
beowulfCharacteristics.name = "Beowulf"
beowulfCharacteristics.occupation= "Hero"
beowulfCharacteristics.foe = "Grendel" Mithilfe von dynamischen Datenobjekten können Sie die Anzahl der in einem Skript verwendeten Variablen verringern. Das vorherige Beispiel zeigt, wie Sie ein einzelnes Objekt mit drei Werten verwenden können, anstatt drei einzelne Variablen zu erstellen.
Die Mitglieder von dynamischen Datenobjekten können wiederum eigene Sätze mit Mitgliedern enthalten. Für diese untergeordneten Mitglieder gelten dieselben Regeln wie für Mitglieder auf der obersten Ebene. Beispielsweise:
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" Zusammenfassung der Syntax von dynamischen Datenobjekten
In diesem Abschnitt wird die Syntax für die Verwendung von dynamischen Datenobjekten in Studio-Skripten zusammengefasst. Weitere Informationen finden Sie in den anderen Abschnitten auf dieser Seite.
Deklarieren Sie ein dynamisches Datenobjekt mit dieser Syntax:
DYNAMIC <objectName> [FROM 'string' | var]
Für den <objectName> gelten dieselben Namenskonventionen wie für Standardvariablen in Studio. Bei Objektnamen wird zwischen Groß- und Kleinschreibung unterschieden.
Die
Verwenden Sie diese Syntax, um einem Objekt Mitglieder hinzuzufügen:
<objectName>.<memberName> = "value".
Bei Mitgliedsnamen wird zwischen Groß- und Kleinschreibung unterschieden. Sie müssen kein Schlüsselwort verwenden, um Mitglieder zu einem Objekt hinzuzufügen, wahlweise können Sie aber
Verwenden Sie diese Syntax, um in einem dynamischen Datenobjekt ein Array zu erstellen:
DYNAMIC <object>
ASSIGN <object>.<member>[<index>].<sub-member>= "value"
Dynamische Datenobjekte deklarieren
Zum Deklarieren eines dynamischen Datenobjekts verwenden Sie im Code das Schlüsselwort DYNAMIC vor dem Namen der Variablen und fügen Sie ihm dann Eigenschaften hinzu. Beispielsweise:
DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero"
ASSIGN beowulfCharacteristics.foe = "Grendel"
Zum Deklarieren von Objektmitgliedern ist kein Schlüsselwort erforderlich. Wahlweise können Sie aber
Verweisen auf Mitglieder eines dynamischen Datenobjekts
Wenn der in einem dynamischen Datenobjekt enthaltene Wert verwendet werden soll, müssen Sie auf das Mitglied verweisen, das den Wert enthält. Verwenden Sie die folgende Syntax:
<dynamicObjectName>.<memberName>
Sie können dies auf dieselbe Weise wie eine Standardvariable verwenden. Sie können in jeder Studio-Aktionseigenschaft, die die Variablenersetzung akzeptiert, sowie in Snippets auf dynamische Datenobjekte verweisen.
Wenn Sie beispielsweise auf das Mitglied für den Namen des folgenden Objekts verweisen möchten, verwenden Sie beowulfCharacteristics.name.
DYNAMIC beowulfCharacteristics
beowulfCharacteristics.name = "Beowulf"
beowulfCharacteristics.occupation= "Hero"
beowulfCharacteristics.foe = "Grendel" Spezielle Objekteigenschaft $value
Dynamische Datenobjekte haben eine spezielle Eigenschaft namens
- Verwenden Sie eine Funktion mit einem Mitglied eines Objekts. Beispiel: beowulfCharacteristics.name.first.
- Kopieren Sie einen Wert aus einer Eigenschaft eines dynamischen Datenobjekts in eine reguläre Variable, indem Sie die Eigenschaft
Sie können
Funktionen mit Objekten
Funktionen sind Codeblöcke, die im Skript aufgerufen und ausgeführt werden können. Funktionen ermöglichen Ihnen die Interaktion mit den Werten in einer Variablen oder in einem Objekt. Funktionen können Werte ändern oder Aufschluss über Werte geben. Beispielsweise gibt es Funktionen, die die Groß- oder Kleinschreibung des Wertes in einer Variablen oder einem Objektmitglied ändern können. Andere Funktionen zählen die Anzahl der Elemente in einem Array oder geben Aufschluss darüber, ob ein Wert numerisch ist.
Es sind mehrere Funktionen verfügbar, die Sie mit den dynamischen Datenobjekten in Ihren Skripten verwenden können. Funktionen können nur für Objektmitglieder ausgeführt werden, nicht für die Objekte selbst.
Zur Verwendung einer Funktion mit einem Objekt nutzen Sie die spezielle Objekteigenschaft
Verwenden Sie die folgende Syntax, um eine Funktion für ein Objektmitglied auszuführen:
Wenn Sie beispielsweise die Funktion
Kopieren von Objektwerten in andere Objekte oder Variablen
Sie können eine Kopie der in einem Objekt enthaltenen Daten erstellen, wenn Sie zwei Versionen der Daten erhalten möchten. So können Sie eine Version ändern und die andere Version unverändert beibehalten. Verwenden Sie dazu die integrierte copy() -Funktion mit dieser Syntax:
DYNAMIC <object1>
DYNAMIC <object2>
<object1> = copy(<object2>)
Die Variable, in die Sie die Daten kopieren, kann ein dynamisches Objekt oder eine standardmäßige Studio-Variable sein. Wenn es sich um eine standardmäßige Variable handelt, wird sie automatisch in ein dynamisches Objekt konvertiert.
Die Funktion copy() belegt mehr Systemressourcen als die Zuweisung einer Referenz. Sie führt eine Tiefenkopie durch, indem sie das Objekt in eine Textdarstellung und dann zurück in ein Objekt konvertiert. Wenn das Objekt, mit dem Sie arbeiten, große Datenmengen enthält, kann sich dieser Vorgang auf die Funktionsweise des Skripts auswirken.
Sie können den Wert aus dem untergeordneten Mitglied eines dynamischen Objekts in das untergeordnete Mitglied eines anderen dynamischen Objekts kopieren. Die Funktion copy() kann nicht mit untergeordneten Mitgliedern verwendet werden. Deshalb müssen Sie die Variablen so einrichten, dass sie gleichwertig sind:
DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.nameSie können den Wert aus dem untergeordneten Mitglied eines dynamischen Objekts in eine standardmäßige Variable kopieren. Dadurch wird die Variable automatisch in ein dynamisches Objekt konvertiert. Wenn Sie dies verhindern möchten, müssen Sie den Namen des dynamischen Objekts und des kopierten untergeordneten Objekts in doppelte Anführungszeichen und geschweifte Klammern einschließen. Dadurch wird verhindert, dass die Variable in ein dynamisches Objekt konvertiert wird. Beispielsweise:
ASSIGN currentContact = "{beowulfCharacteristics.foe}"Als Alternative zum Formatieren des Objektnamens können Sie auch die Eigenschaft
ASSIGN currentContact = beowulfCharacteristics.foe.$valueZuweisen eines Verweises auf einen Objektwert zu anderen Objekten oder Variablen
Sie können einen Verweis auf ein dynamisches Datenobjekt zu einem anderen dynamischen Objekt zuweisen. Beispielsweise:
DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero"
ASSIGN beowulfCharacteristics.foe = "Grendel"
DYNAMIC currentContact
ASSIGN currentContact = beowulfCharacteristicsNachdem die obige Zuweisung festgelegt wurde, verweisen currentContact und beowulfCharacterics beide auf dieselben physischen Daten. Wenn Sie den Wert eines Untermitglieds in einem der beiden dynamischen Objekte ändern, ändert sich auch der Wert im anderen Objekt. Wenn Sie beispielsweise currentContact.name in Beowulf Herot ändern, wird der Wert von
Es ist nicht möglich, einem einzelnen untergeordneten Mitglied einen Verweis zuzuweisen. Sie können den Wert eines untergeordneten Mitglieds von einem dynamischen Objekt in ein anderes kopieren. Dadurch wird der Wert dupliziert. Wenn Sie einen Wert ändern, wird der andere Wert nicht automatisch geändert.
Dynamisches Datenobjekt aus JSON oder XML erstellen
Sie können ein dynamisches Datenobjekt zum Parsen von JSON oder XML verwenden.
Definieren Sie das dynamische Datenobjekt und verwenden Sie den Befehl FROM, um die JSON- oder XML-Daten anzugeben. Verwenden Sie dabei die folgende Syntax:
DYNAMIC <objectName> [FROM 'string' | var]
Sie können einen 'string' angeben, der JSON- oder XML-Daten enthält. Außerdem können Sie den Namen einer Skriptvariablen var angeben, die einen JSON-String oder XML-Daten enthält. Wenn Sie einen String 'string' verwenden, muss er sich vollständig auf einer einzelnen Zeile befinden. Wenn 'string' auf eine zweite Zeile umgebrochen wird, entsteht ein Fehler.
Beispielsweise:
DYNAMIC beowulfWeapons FROM '{ "key1": "Hrothgars gift", "key2": "Hrunting", "key3": "Naegling"}'Die Ergebnisse lauten:
beowulfWeapons.key1 = "Hrothgars gift"
beowulfWeapons.key2 = "Hrunting"
beowulfWeapons.key3 = "Naegling"Wenn die JSON-Schlüssel-Wert-Paare aus dem vorherigen Beispiel in einer Variable namens famousSwords enthalten wären, könnten Sie das dynamische Datenobjekt stattdessen folgendermaßen erstellen:
DYNAMIC epicMonsterDoom FROM famousSwordsBeide Methoden zum Erstellen des Objekts führen zu denselben Ergebnissen.
In Studio wird __type (mit zwei Unterstrichen) beim Parsen von JSON verwendet. Es kann nicht als Schlüsselname in dynamischen Datenvariablen verwendet werden, da sie JSON parsen können. Wird es als Schlüsselname in einer dynamischen Datenvariable verwendet, tritt ein Fehler auf, wenn Sie das Skript speichern oder wenn das Skript die Aktion ausführt.
Zuweisen eines JSON-Strings zu einer Variablen
Sie können JSON-Strings auch einer Variablen anstatt einem dynamischen Objekt zuweisen. Dies ist nicht die bevorzugte Methode für die Arbeit mit JSON-Strings. Sie bietet Ihnen nicht die Flexibilität, die Sie erhalten, wenn Sie JSON-Code mit dynamischen Objekten verwenden. In manchen Fällen muss diese Methode jedoch verwendet werden.
Bevor Sie einen JSON-String einer Variablen zuweisen können, müssen Sie die geschweifte Klammer ({) und das doppelte Anführungszeichen (") durch Escape-Zeichen ersetzen. Sie können einen Texteditor verwenden, um die Zeichen manuell zu ersetzen, oder Sie verwenden die replace()-Funktion im Skript. In der Variablenzuweisung muss vor dem JSON-String ein Dollarzeichen ($) stehen, wie im folgenden Beispiel gezeigt. Das Dollarzeichen gibt einen Wert an, der Escape-Zeichen enthält.
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\"}]}}}}}]}"
Erstellen eines dynamischen Datenobjekts auf Basis einer REST-Antwort
Dynamische Datenobjekte werden automatisch aus Antworten von REST API-Aufrufen erstellt. Diese Antworten können in JSON oder XML sein. Studio wandelt sie in dynamische Datenobjekte in Skripten um. Beispielsweise:
ASSIGN GetRequest = "<API Endpoint>"
ASSIGN DynamicReturn = Proxy.MakeRestRequest(GetRequest,"",0,"GET")
ASSIGN fileContent = "{DynamicReturn.files.file}"In diesem Beispiel gibt die Funktion MakeRestRequest() das dynamische Datenobjekt DynamicReturn zurück. Sie müssen das Schlüsselwort DYNAMIC nicht mit dieser Variablen verwenden, da das Skript sie automatisch zu einem dynamischen Datenobjekt macht.
Um das dynamische Datenobjekt zu parsen, das die REST-Antwort enthält, verwenden Sie ASSIGN fileContent = "{DynamicReturn.files.file}". Dadurch wird der extrahierte Wert ({DynamicReturn.files.file}) der Variablen fileContent zugewiesen. Sie können ASSIGN fileContent = DynamicReturn.files.file.$value auch für das Parsen der Antwort verwenden.
Vorbereiten von Payload-Daten für REST-API-Aufrufe
Mithilfe der Funktion asjson() können Sie Payload-Daten für REST-API-Aufrufe vorbereiten und im JSON-Format senden. Es wird empfohlen, für diese Aufgabe die
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 diesem Beispiel wird TokenInput als dynamisches Objekt mit drei Mitgliedern deklariert: grant_type, username und password. TokenJsonInput wird so deklariert, dass TokenInput in Form eines Strings enthalten ist. Dazu wird die Funktion
Dynamisches Datenobjekt in JSON oder XML umwandeln
Sie können den Inhalt eines dynamischen Objekts in einen JSON- oder XML-String umwandeln. Damit werden die Daten im Objekt serialisiert und in ein Format konvertiert, das über das Internet übertragen werden kann.
Verwenden Sie dazu die Funktion asjson() oder asxml() mit dem Objekt, das konvertiert werden soll. In Studio können Sie diese Einstellung an zwei Stellen vornehmen: entweder in einer Snippet-Aktion oder in der Aktionseigenschaft, die die konvertierten Daten des Objekts benötigt.
Beide Vorgehensweisen funktionieren auf dieselbe Weise. Der Vorteil der Erstellung einer Variablen in einem Snippet, die das umgewandelte Objekt enthält, besteht jedoch darin, dass leichter zu sehen ist, wo die Umwandlung passiert. Sie müssen nicht wissen, welche Aktion den konvertierten Inhalt des Objekts erfordert.
Zum Konvertieren eines Objekts in einem Snippet verwenden Sie die folgende Syntax:
ASSIGN varJSON="{myDynamic.asjson()}"
Verwenden Sie in der Eigenschaft der Studio-Aktion, für die die JSON- oder XML-Daten erforderlich sind, den Namen der Variablen, die Sie im Snippet verwendet haben. Auf Basis des Syntaxbeispiels konfigurieren Sie die Aktionseigenschaft mit
Zum Konvertieren eines Objekts in der Aktionseigenschaft konfigurieren Sie die Aktionseigenschaft mit dem Namen des Objekts und der asjson()- oder asxml()-Funktion in geschweiften Klammern. Beispiel:
Alle Mitglieder eines dynamischen Objekts werden als Stringwerte interpretiert, auch numerische und boolesche
Ein Datentyp, der zwei mögliche Werte hat: wahr und falsch. Werte. Bei Werten, die keine Strings sind, müssen Sie den JSON-Code manuell parsen, um die doppelten Anführungszeichen zu entfernen. Dazu können Sie die
Anzeigen der Inhalte von dynamischen Objekten
Wenn Sie den Debugger ausführen, können Sie den Inhalt von dynamischen Objekten im
- Doppelklicken Sie in Studio auf eine
- Fügen Sie bei Bedarf Snippet-Code hinzu.
- Klicken Sie auf der Registerkarte "
- Klicken Sie auf der Registerkarte "
und wählen Sie Schritt in 
aus. Wenn Sie den Code nicht Zeile für Zeile durchlaufen möchten, klicken Sie auf das Symbol Debuggen starten. - Klicken Sie auf das Symbol Schritt und beobachten Sie den Inhalt auf der Registerkarte "
- Wenn Sie alle Codezeilen durchlaufen oder auf Debuggen starten geklickt haben, werden auf der Registerkarte "
-
Sie können neben jedem String-Array oder neben jedem dynamischen Objekt im Code auf das Symbol + klicken, um den jeweiligen Eintrag zu erweitern. Wenn es sich beim Inhalt um ein anderes Array oder Objekt handelt, können Sie die Struktur weiter erweitern, um die jeweiligen Inhalte anzuzeigen.
Skriptvalidierungsfehler und dynamische Objekte
Wenn Sie ein Skript speichern, validiert Studio alle darin enthaltenen Informationen. Dabei wird z. B. überprüft, ob alle dynamischen Objekte, auf die im Skript verwiesen wird, im Skript deklariert sind. In Studio muss die Objektdeklaration für alle im Skript referenzierten Objekte validiert werden. Andernfalls tritt ein Fehler auf, sogar dann, wenn das Objekt in einem anderen Skript deklariert ist und an das überprüfte Skript übergeben wird. Wenn Ihr Skript ein nicht deklariertes Objekt enthält, wird beim Speichern der folgende Fehler angezeigt: "Funktion '[name]' wurde nicht definiert".
Es gibt zwei Möglichkeiten, um dies zu vermeiden. Bei der ersten Option fügen Sie dem Snippet, in dem auf das Objekt verwiesen wird, eine
IF TEST = 1
{
DYNAMIC dynaObject
}
DYNAMIC dynaObject.prop = 1Bei der zweiten Option fügen Sie dem Skript ein