動態資料物件

本説明頁面上的資訊同時適用於 CXone StudioDesktop Studio

物件是資料結構,可以在單個變數中包含多個值。當您在指令碼中收集了與「事物」相關的值時,它們就會派上用場。例如,您可能有一組與聯絡人有關的資料,如姓名、電話號碼和電郵地址。您可以將所有這些值存儲在一個物件中。這樣做的好處是可以減少指令碼中使用的變數數量。

Studio 支援動態資料類型物件。這種類型可以處理沒有靜態格式或類型的資料,如 XML 或 JSON。

您可以透過在 Snippet 代碼中進行聲明或者透過解析 JSON 或 XML 來建立動態資料物件。它們也是根據來自 API 調用的回應和某些框架動作建立的。

您可以在任何 Studio 動作中使用動態資料物件,在這些動作中您可以使用標準變數。動態資料物件可用於存儲資料,就像標準變數一樣。它們還有其他用途。例如,您可以使用它們來:

指令碼中動態資料變數和對象的數量可以影響追蹤。對於包含大量動態變數的指令碼,您可能會看到性能問題。它們包含的資料越多,處理每個動作所需的時間就越長。

關於動態資料物件的關鍵事實

  • 動態資料物件儲存的值稱為成員。
  • 每個成員都有一個名稱。例如,在 beowulfCharacteristics.occupation 中,beowulf 是物件,occupation 是其中一個成員的名稱。
  • 對象成員的類型由運行時間決定。編譯器儲存有關屬性的資訊。運行時,對資訊進行檢查並執行動作。因此,編譯器不會對動態資料物件進行錯誤捕獲。相反,錯誤會引發運行時間異常。
  • 動態資料物件可以有動態建立的成員。在您的指令碼中聲明動態資料物件後,您可以將值指派給後續行中物件的成員。您甚至可以將值指派給其他 Snippet 中的成員。如果成員不存在,則會自動建立並為其指定值。
  • 動態資料物件可以存儲多種類型的資料。標準 Snippet 變數是隱式類型的,這表示類型是在 Studio 編譯器編譯代碼時確定的。動態資料物件類型為動態資料。對象的成員是隱式類型。
  • 在引用動態資料物件的成員時,大小寫很重要。例如,如果您試圖用 ASSIGN fileContent = "{beowulfcharacteristics.Files.file}" 來解析 beowulfCharacteristics.files.file 的值,將一無所獲。這是因為動態物件成員 Files.filefiles.file 並不相同。
  • 所有動態資料物件成員都具有特殊屬性,$value。您無法為該屬性指派值。它允許您對成員執行某些動作,否則這些動作將不起作用。
  • 動態資料物件及其成員必須小於 32 KB。將物件轉換為 JSON 或 XML 時,產生的內容必須小於 32 KB。如果轉換物件內容大小超過該限制,則會被截斷。

嘗試一下

下載 物件範例指令碼並將 匯入Studio中。本說明頁面中的一些範例可在範例指令碼中的 Snippet 動作中找到。您可以打開 Snippet Editor 視窗並運行 偵錯程式,查看每個範例如何工作。

對象成員

動態資料物件以鍵/值對的形式儲存其屬性,也稱為成員。鍵是成員的名稱,也是物件中變數的名稱。在下面的範例中,鍵是 nameoccupationfoe。每個鍵都有一個與之相關的值,該值列在等號右邊的雙引號中。

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

動態資料物件允許您減少指令碼中使用的變數數量。先前的範例顯示,您可以使用單個物件來儲存三個值,而不是建立三個唯一變數。

動態資料物件的成員可以有自己的成員集。這些子成員與一級成員一樣遵循相同的規則。例如:

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" 

動態資料物件語法摘要

本節總結了與在 Studio 指令碼中使用動態資料對象相關的語法。您可以在本頁的其他部分了解更多資訊。

使用此語法聲明動態資料物件:

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

<objectName> 必須遵循與 Studio 中標準變數相同的命名準則。物件名稱區分大小寫。

FROM 子句為可選項。您可以使用它從var包含 JSON 或 XML 字串的字串 'string' 或指令碼變數內容建立物件。如果您使用 'string',則其必須完全位於單一行上,並用單引號括起來。

使用此語法向物件新增成員:

<objectName>.<memberName> = "value"

成員名稱區分大小寫。您不必使用關鍵字將成員新增到物件,但如果您想,可以使用 ASSIGN

使用此語法在動態資料物件中建立陣列

DYNAMIC <object>

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

聲明動態資料物件

要聲明動態資料物件,請在變數名之前使用代碼中的關鍵字 DYNAMIC,然後為其新增屬性。例如:

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

您不需要關鍵字來聲明物件成員。如果您願意,可以使用 ASSIGN。引用成員時,如果該成員尚未存在,則會動態建立該成員。

引用動態資料物件成員

當您需要使用動態資料物件所包含的值時,必須引用儲存該值的成員。使用以下語法:

<dynamicObjectName>.<memberName>

您可以像使用標準變數一樣使用它。您可以在任何接受變數替換的 Studio 動作屬性中引用動態資料物件,也可以在 Snippet 中引用動態資料物件。

例如,要引用下面物件的成員,您可以使用 beowulfCharacteristics.name

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

特殊物件屬性值

動態資料物件有一個特殊屬性,$value。該屬性允許以其他方式對物件及其值執行動作,而其他方式是不可能做到的。您可以使用它來:

  • 對物件的成員使用函數。例如:beowulfCharacteristics.name.first.$value.length()。您可以在下一節中了解更多關於使用物件運行函數的資訊。
  • 使用 $value 屬性將值從動態資料物件內容複製到常規變數中:x = name.first.$value

您不能將值指派給 $value。其是唯讀狀態。

帶物件的函數

函數是可以調用並在您的指令碼中運行的代碼塊。函數允許您與變數或物件中的值互動。函數可以修改值或告知您其相關資訊。例如,有些函數可以轉換變數或物件成員值的大小寫。還有其他函數可以計算陣列中元素的數量,或者告訴您值是否為數字。

有許多函數可供您在指令碼中用於動態資料物件。您只能對物件成員而非物件本身運行函數。

要將函數用於物件,請使用特殊物件屬性 $value。此屬性為唯讀屬性,不會在物件中建立 $value 屬性。其會阻止函數名稱成為物件的屬性。其會返回所使用物件成員的字串值。

使用以下語法在物件成員上運行函數:obj.member.$value.function().

例如,要在 name.first上執行 length() 函數,應使用:

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

複製物件值到另一個物件或變數

如果需要兩個版本的資料,則可以建立物件所儲存資料的副本。這使您可以在不影響另一個資料的情況下變更一個資料。要實現此功能,請按照以下語法使用內置的 copy() 函數

DYNAMIC <object1>

DYNAMIC <object2>

<object1> = copy(<object2>)

您複製資料的變數可以是動態物件,也可以是標準 Studio 變數。如果是標準變數,則會自動轉換為動態物件。

函數 copy() 比指派引用使用了更多的系統資源。它透過將對象轉換為文字表示,然後再轉換回對象來執行深度複製。如果您正在處理的物件包含大量資料,此過程可能會影響指令碼的功能。

您可以將動態物件子成員的值複製到另一個動態物件的子成員中。copy() 函數不能同時處理兩個子成員,因此您需要將變數設定為彼此相等:

DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.name

您可以將動態物件子成員中的值複製到標準變數中。這會自動將變數轉換為動態物件。為防止出現這種情況,動態物件和您要複製的子成員的名稱必須用雙引號和大括號括起來。這將防止變數被轉換為動態物件。例如:

ASSIGN currentContact = "{beowulfCharacteristics.foe}"

格式化物件名稱的另一種方法是新增 $value 屬性:

ASSIGN currentContact = beowulfCharacteristics.foe.$value

將一個物件值的引用指派給另一個物件或變數

您可以將對動態資料物件的引用指派給另一個動態物件。例如:

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

DYNAMIC currentContact

ASSIGN currentContact = beowulfCharacteristics

在上述指派後,currentContactbeowulfCharacterics都引用了相同的物理資料。如果變更任一動態物件中子成員的值,另一物件中的值也會改變。例如,如果將currentContact.name變更為 Beowulf HerotbeowulfCharacteristics.name 的值會自動更新為 Beowulf Herot。如果將 beowulfCharacteristics.name 的值變更為 SparkycurrentContact.name 的值將自動更新為 Sparky

您不能為單個子成員指派引用。您不能將一個動態物件中的子成員的值複製到另一個動態物件中。這將複製值。如果變更一個值,則不會自動變更另一個值。

從 JSON 或 XML 建立一個動態資料物件

您可以使用動態資料變數來解析 JSON 或 XML。

定義動態資料物件,並使用 FROM 命令以這種語法指定 JSON 或 XML 資料:

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

您可以指定包含 JSON 或 XML 資料的 'string'。您可以指定包含 JSON 字串或 XML 資料的指令碼變數 var 的名稱。如果您使用 'string',則其必須完全位於一行上。如果 'string' 斷開到第二行,則會導致錯誤。

例如:

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

結果如下:

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

如果前面範例中使用的 JSON 鍵值對包含在稱為 famousSwords 的變數中,您就可以建立類似這樣的動態資料物件:

DYNAMIC epicMonsterDoom FROM famousSwords

建立物件的兩種方法的結果相同。

Studio 中,解析 JSON 時使用 __type(包含兩個底線字元)。此變數不能在動態資料變數中用作鍵名稱,因為後者可以解析 JSON。如果您在動態資料變數中使用它作為鍵名,當您儲存指令碼或指令碼執行動作時,會導致錯誤

將 JSON 字串賦值給變數

處理 JSON 字串時的另一個選擇是將其賦值給變數而不是動態物件。這不是處理 JSON 字串的首選方法。在管理和使用代碼時,此方法不像動態物件中的 JSON 那樣靈活。不過,有時也需要這樣做。

在將 JSON 字串賦值給變數之前,必須用轉義字元替換大括弧({)和雙引號(")字元。您可以使用文字編輯器手動替換這些字元,也可以使用replace()函數在指令碼中進行替換。在變數賦值中,JSON 字串的首碼必須是美元符號 ( $ ),如下例所示。美元符號表示包含轉義字元的值。

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

從 REST 回應中建立一個動態資料物件

動態資料物件是由 REST API 調用的回應自動建立。這些回應可以是 JSON 或 XML 格式。在指令碼中 Studio 將其轉換為動態資料物件。例如:

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

在此範例中,MakeRestRequest() 函數返回一個動態資料物件 DynamicReturn。您不需要對這個變數使用 DYNAMIC 關鍵字,因為指令碼會自動將其變成一個動態資料物件。

為了解析包含 REST 回應的動態資料物件,使用 ASSIGN fileContent = "{DynamicReturn.files.file}"。這將提取的值 ({DynamicReturn.files.file}) 指派給 fileContent 變數。您還可以使用 ASSIGN fileContent = DynamicReturn.files.file.$value 解析回應。

為 REST APIC 調用準備有效載荷資料

您可以為 REST API 調用準備有效載荷資料,並使用 asjson() 函數將其傳送為 JSON。此任務的首選方法是 REST API 動作。不過,您也可以用 Snippet 來完成此任務。例如:

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

在此範例中,TokenInput 被聲明為具有三個成員的動態物件,即 grant_typeusernamepasswordTokenJsonInput 被聲明為使用 asjson() 函數以字串化形式儲存 TokenInput。在範例的最後一行,變數 TokenResponse 被聲明為儲存 REST 請求,然後可以在指令碼代碼中用於傳送請求。

將動態資料物件轉換為 JSON 或 XML

您可以將動態物件的內容轉換為 JSON 字串或 XML 字串。這將物件中的資料序列化,並將其轉換為可以透過 Internet 傳輸的格式。

要如此操作,請對要轉換的物件使用 asjson()asxml() 函數。在 Studio中,您可以在兩處進行此動作,在 Snippet 動作中或需要從物件轉換資料的動作屬性中。

這兩種方法操作方式一樣。然而,在 Snippet 中建立一個變數來儲存轉換後的物件的好處是,這樣會更容易看到轉換在哪裡發生。您不需要知道哪個動作需要物件的轉換內容。

要在 Snippet 中轉換物件,使用下面的語法:

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

在需要 JSON 或 XML 資料的 Studio 動作的屬性中,請使用您在 Snippet 中使用的變數名稱。在語法範例中看,您可以使用 varJSON 設定動作屬性。

要在動作屬性中轉換一個物件,請透過物件的名稱和大括號括起來的 asjson()asxml() 函數來設定動作屬性。例如:{myDynamic.asjson()}

動態物件的所有成員都被視為字串值,包括數值和布爾Closed 具有兩種可能值的子了類型:true 和 false。值。對於不是字串的值,需要手動解析 JSON 以刪除雙引號。您可以使用 replace() 函數進行處理。

檢視動態物件的內容

當您執行偵錯程式時,可以在 Snippet 編輯器視窗檢視動態物件的內容。這使您能夠在代碼的每一步驗證物件是否保留其應該保留的資料。

  1. Studio中,點擊兩下 Snippet 動作。
  2. 如有必要,新增 snippet 代碼。
  3. Debugger 標籤上,點擊變數為樹標籤。
  4. Debugger 標籤上,點擊開始偵錯圖示旁邊的向下箭頭,選擇單步執行一系列水平線,箭頭從一條線指向其下的一條線。。如果您不想逐行瀏覽代碼,可點擊開始偵錯圖示。
  5. 點擊步驟一系列水平線,箭頭從一條線指向其下的一條線。圖示,觀察 Variables as Tree 標籤上的內容。每次點擊步驟,此欄位就會隨著前一行代碼之後的指令碼中的變數和物件更新。如果點擊開始偵錯,則跳過此步驟。
  6. 當您跳過所有的代碼行,或者如果您點擊了開始偵錯Variables as Tree 標籤將顯示所有變數、物件、以及它們在 snippet 末尾的內容。
  7. 您可以點擊代碼中任何字串陣列或動態物件旁邊的 + 圖示來展開它們。如果內容是另一個陣列或物件,可以繼續展開樹,查看每個實體所包含的項目。

指令碼驗證錯誤和動態物件

儲存指令碼時,Studio 會驗證其中的所有資訊。其檢查的內容之一是指令碼中聲明的指令碼所引用的所有動態物件。Studio 要求對正在驗證的指令碼中引用的所有物件進行物件聲明。即使在其他指令碼中聲明了物件,並將其傳入正在驗證的指令碼中,仍會導致錯誤。如果您在指令碼中取消聲明了一個物件,則在儲存時會出現「尚未定義「[name]」函數」錯誤。

您有兩種方式避免這種情況。一種方式是在引用物件的 Snippet 中新增帶有 TEST 變數的 IF 語句。在 IF 語句的大括號中,聲明動態物件。例如:

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

第二個方式是在包含物件聲明的指令碼中新增 SNIPPET,而不是其他。如果在指令碼中傳遞了多個物件,您可以在單個 SNIPPET 中聲明所有物件。這有助於使您指令碼中的其他 SNIPPET 動作整齊。您不需要將此動作與指令碼中的其他動作連接起來。其存在與指令碼中是為了滿足指令碼在驗證時對物件聲明的要求。