動態資料物件

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

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

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

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

• 產生 REST API 調用。
• 處理來自 Workflowdata 動作的回應。此動作返回動態資料物件中的工作流程資料。

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

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

嘗試一下

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

對象成員

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

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() 函數不能同時處理兩個子成員，因此您需要將變數設定為彼此相等：

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

在上述指派後，currentContact 和 beowulfCharacterics都引用了相同的物理資料。如果變更任一動態物件中子成員的值，另一物件中的值也會改變。例如，如果將currentContact.name變更為 Beowulf Herot，beowulfCharacteristics.name 的值會自動更新為 Beowulf Herot。如果將 beowulfCharacteristics.name 的值變更為 Sparky，currentContact.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

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

將 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_type、username 和 password。TokenJsonInput 被聲明為使用 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()}。

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

處理 JSON 鍵中的特殊字元

變數名中的特殊字元會導致Studio中出現錯誤。如果您正在使用的 JSON 鍵名稱中包含特殊字元，則必須解決此限制。例如，在使用包含 CONTENT-TYPE 鍵值對的標頭時，這可能是一個問題。當在動態物件中時，諸如 requestPayload.HEADERS.CONTENT-TYPE = "APPLICATION/JSON" 之類的物件成員將導致錯誤。

一種解決方案是用動態物件中的文字取代特殊字元。將物件轉換為 JSON 後，將文字替換為正確的特殊字元。以下範例顯示了一個包含 CONTENT-TYPE 鍵的動態物件成員，其中使用文字 HYPHENPLACEHOLDER 代替連字號 ( - )：

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

上例中的第二行和第三行顯示動態物件轉換為 JSON，然後使用replace()函數將 HYPHENPLACEHOLDER替換為連字號。

檢視動態物件的內容

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

   

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

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

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

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

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