動的データオブジェクト

オブジェクトは、1つの変数内に複数の値を保持できるデータ構造です。これはスクリプトの中で、ある"もの"に関連する値のコレクションがある場合に便利です。例えば、名前、電話番号、電子メールアドレスなど、コンタクトに関する一連のデータがあるとします。これらの値をすべて1つのオブジェクトに格納することができます。これにより、スクリプト内で使用する変数の数を減らすというメリットがあります。

Studioは、ダイナミックデータ型のオブジェクトをサポートしています。この型は、XMLやJSONのような固定フォーマットやタイプを持たないデータを扱うことができます。

Snippetコードで宣言するか、JSONやXMLを解析することで動的データオブジェクトを作成できます。また、APIコールからのレスポンスや特定のフレームワークのアクションからも作成されます。

ダイナミックデータオブジェクトは、標準の変数を使用できるすべてのStudioアクションで使用できます。ダイナミックデータオブジェクトは、標準変数と同じように、データを保持するために使用できますが、それ以外の用途もあります。例えば、これらを使って以下のことを行えます。

REST API呼び出しを生成する。
Workflowdataアクションからの応答を処理する。このアクションは、動的データオブジェクトでワークフローデータを返します。

スクリプト内の動的データ変数とオブジェクトの数は、トレースに影響を与える可能性があります。多くの動的変数を含むスクリプトのパフォーマンスの問題が発生する可能性があります。含まれるデータが多いほど、各アクションを処理する時間が長くなります。

ダイナミックデータオブジェクトに関する重要ポイント

ダイナミックデータオブジェクトが保持する値はメンバーと呼ばれます。
各メンバーはその名前で識別されます。例えば、beowulfCharacteristics.occupationではbeowulf がオブジェクトで、occupationはそのメンバーのうちの1つの名前です。
オブジェクトメンバーの型は実行時に決定されます。コンパイラはプロパティに関する情報を保存します。ランタイムにその情報が調査され、処理されます。このため、コンパイラではダイナミックデータオブジェクトのエラーが検出されません。その代わり、エラーがあるとランタイム例外が発生します。
ダイナミックデータオブジェクトは、動的に作成されるメンバーを持つことができます。スクリプトでダイナミックデータオブジェクトを宣言した後、その後の行でオブジェクトのメンバーに値を代入します。他のスニペットでメンバーに値を割り当てることも可能です。メンバーが存在しない場合は、自動的に作成され、指定された値が割り当てられます。
ダイナミックデータオブジェクトは多くの種類のデータを格納することができます。標準のスニペット変数は暗黙的に型指定されるので、Studioコンパイラがコードをコンパイルするときに型が決定されます。ダイナミックデータオブジェクトはダイナミックデータ型です。オブジェクトのメンバーは暗黙的に型指定されます。
ダイナミックデータオブジェクトのメンバーを参照する際は、大文字と小文字の区別が重要です。例えば、ASSIGN fileContent = "{beowulfcharacteristics.Files.file}"でbeowulfCharacteristics.files.fileの値を解析しようとすると、何も返されません。これは、Files.fileがfiles.fileと同じではないためです。
ダイナミックデータオブジェクトのすべてのメンバーは、$valueという特別なプロパティを持っています。このプロパティに値を割り当てることはできません。これにより、他の方法では機能しないような特定のアクションをメンバーで実行できるようになります。
ダイナミックデータオブジェクトとそのメンバーは32 KB未満でなければなりません。オブジェクトをJSONまたはXMLに変換する場合、変換後のコンテンツは32KB未満でなければなりません。変換されたオブジェクトの内容がその制限を超える場合、切り捨てられます。

試してみる

オブジェクトの例スクリプトをダウンロードしてStudioにインポートします。このヘルプページの例の多くは、サンプルスクリプトのSnippetアクションで利用可能です。Snippet editor ウィンドウを開いてデバッガーを実行することで、各例の動作を確認できます。

オブジェクトメンバー

ダイナミックデータオブジェクトは、プロパティ（メンバーとも呼ばれます）をキーと値のペアの形で保持します。キーはメンバーの名前で、オブジェクト内にある変数の名前のようなものです。次の例では、name、occupation、foeがそれぞれキーとなります。各キーには値が関連付けられ、これは等号の右側に二重引用符で囲んで指定します。

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

ダイナミックデータオブジェクトによって、スクリプト内で使用される変数の数を減らすことができます。先の例は、3つの一意の変数を作成する代わりに、1つのオブジェクトを使って3つの値を保持する方法を示しています。

ダイナミックデータオブジェクトのメンバーが、独自のメンバーセットを持つこともあります。これらのサブメンバーは、最初のレベルのメンバーと同じルールに従います。例：

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句はオプションです。これを使用して、文字列'string'またはJSONまたはXML文字列を含むスクリプト変数varの内容からオブジェクトを作成することができます。'string'を使用する場合は、すべてを1行に指定し、一重引用符で囲む必要があります。

メンバーを追加するには次の構文を使用します。

<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を使うことはできます。メンバーを参照すると、そのメンバーがまだ存在しない場合は動的に作成されます。

ダイナミックデータオブジェクトのメンバーを参照する

ダイナミックデータオブジェクトに含まれている値を使用するには、その値を保持するメンバーを参照する必要があります。次の構文を使用します：

これは標準変数と同じ方法で使用できます。ダイナミックデータオブジェクトは、変数代入を受け入れるStudioのアクションプロパティおよびスニペットで参照することができます。

例えば、以下のオブジェクトのnameというメンバーを参照するには、beowulfCharacteristics.nameを使用します。

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

特殊なオブジェクトプロパティ$value

ダイナミックデータオブジェクトは、$valueという特殊なプロパティを持っています。このプロパティを使用すると、オブジェクトとその値を使って、他の方法では不可能なことが可能になります。これを使用して次のことが可能です。

関数でオブジェクトのメンバーを使用する。例：beowulfCharacteristics.name.first.$value.length()。オブジェクトを指定した関数の実行についての詳細は、次のセクションを参照してください。
$valueプロパティを使用して、ダイナミックデータオブジェクトのプロパティから通常の変数に値をコピーする：x = name.first.$value。

$valueに値を割り当てることはできません。これは読み取り専用です。

オブジェクトと関数

関数は、スクリプト内で呼び出して実行できるコードのブロックです。関数を使えば、変数やオブジェクト内の値を操作することができます。関数で値を変更したり、値に関する情報を取得することができます。例えば、変数やオブジェクトメンバーの値の大文字小文字を変換する関数があります。また、配列の要素数を数えたり、値が数値かどうかを判別したりする関数もあります。

スクリプト内のダイナミックデータオブジェクトで使用できる関数がいくつも用意されています。関数を実行できるのはオブジェクトのメンバーに対してだけで、オブジェクト自体に対しては実行できません。

オブジェクトで関数を使用するには、特殊オブジェクトプロパティの$valueを使用します。このプロパティは読み取り専用で、オブジェクトに$valueプロパティが作成されることはありません。これにより、関数名がオブジェクトのプロパティになるのを防ぐことができます。このプロパティは、一緒に使われているオブジェクトメンバーのリテラル文字列値を返します。

オブジェクトメンバーに対して関数を実行するには、以下の構文を使用します：obj.member.$value.function()。

例えばlength()関数をname.firstに対して実行するには、次のようにします。

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

オブジェクトの値を別のオブジェクトまたは変数にコピーする

データの2つのバージョンが必要な場合は、オブジェクトが保持するデータのコピーを作成できます。これにより、もう一方に影響を与えることなく一方を変更することができます。これには、組み込み関数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

上記の代入後、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'を使用する場合は、すべてを1行に指定する必要があります。'string'が改行されて2行目に及ぶ場合、エラーが発生します。

例：

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（アンダースコア2文字付き）が使用されます。JSONの解析が可能なので、ダイナミックデータの変数内のキー名としては使用できません。これをダイナミックデータ変数のキー名として使用すると、スクリプトの保存時やスクリプトによるアクションの実行時にエラーが発生します。

JSON文字列を変数に代入する

JSON文字列で作業する際、もう1つの選択肢としてダイナミックオブジェクトの代わりに変数に代入することができます。これは、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 API呼び出し用のペイロードデータを準備する

REST API呼び出しを生成し、関数asjson()を使用してJSONとして送信します。このタスクには、REST APIアクションを使用する方法を推奨します。しかし、スニペット内で実行することも可能です。例：

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の3つのメンバーを持つダイナミックオブジェクトとして宣言されています。TokenJsonInputは、関数asjson()を使用してTokenInputを文字列形式で保持するために宣言されています。この例の最後の行では、REST要求を保持するために、TokenResponse変数が宣言されており、これをスクリプトコード内で使用して要求を送信することができます。

動的データオブジェクトをJSONまたはXMLに変換する

ダイナミックオブジェクトの内容をJSON文字列またはXML文字列に変換できます。これにより、オブジェクト内のデータをシリアル化し、インターネットで送信できる形式にします。

これを行うには、関数asjson()またはasxml()を使用して、変換するオブジェクトを指定します。Studioでは、これをSnippetアクションか、オブジェクトから変換したデータを必要とするアクションプロパティのどちらかの2つの場所で行うことができます。

どちらの方法も同じように機能します。ただし、変換されたオブジェクトを保持する変数をSnippetに作成する利点は、変換が行われている場所を簡単に確認できることです。どのアクションがオブジェクトの変換された内容を必要とするかを知る必要はありません。

Snippetでオブジェクトを変換するには、以下の構文を使用してください。

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

JSONデータまたはXMLデータが必要なStudioアクションのプロパティで、Snippetで使用した変数名を使用します。構文の例では、varJSONでアクションプロパティを設定することになります。

アクションプロパティでオブジェクトを変換するには、アクションプロパティをオブジェクトの名前と関数asjson()またはasxml()を中括弧で囲んで設定します。例:{myDynamic.asjson()}。

ダイナミックオブジェクトのすべてのメンバーは、数値やBoolean 真と偽の2つの値を持つデータ型。値を含め、文字列値として扱われます。文字列でない値の場合は、JSONを手動で解析して二重引用符を削除する必要があります。これは関数replace()を使用して行うこともできます。

JSONキーの特殊文字を扱う

変数名に特殊文字があると、Studioでエラーが発生します。使用するJSONの名前に特殊文字を含むキーがある場合、この制限を回避しなければなりません。たとえば、これはCONTENT-TYPEキーと値のペアを含むヘッダーを扱うときなどに問題になります。ダイナミックオブジェクトの場合、requestPayload.HEADERS.CONTENT-TYPE = "APPLICATION/JSON"のようなオブジェクトメンバーはエラーの原因となります。

解決策の1つとして、ダイナミックオブジェクトの中で特殊文字をテキストに置き換えることができます。そしてオブジェクトをJSONに変換した後、テキストを正しい特殊文字に置き換えます。次の例では、ダイナミックオブジェクトメンバーの持つCONTENT-TYPEキーでハイフン(-)の代わりにテキスト「HYPHENPLACEHOLDER」を使用しています。

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

先の例の2行目と3行目では、ダイナミックオブジェクトが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.

In Studio, double-click on a Snippet action.
Add snippet code, if necessary.
On the Debugger tab, click the Variables as Tree tab.
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.
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.
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.
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がスクリプト内のすべての情報を検証します。そのチェック項目の1つとして、スクリプト内で参照されているすべてのダイナミックオブジェクトが、スクリプト内で宣言されているかどうかを確認します。Studioでは、検証対象のスクリプトで参照されるすべてのオブジェクトにオブジェクト宣言が必要です。オブジェクトが別のスクリプトで宣言され、検証中のスクリプトに渡されたとしても、エラーは発生します。スクリプト内に未宣言のオブジェクトがあると、保存時に「Function '[name]' has not been defined」というエラーが表示されます。

これを避けるには、2つの方法があります。その1つがオブジェクトを参照するスニペットにTEST 変数を持つIFステートメントを追加する方法です。IFステートメントの中括弧内で、ダイナミックオブジェクトを宣言します。例：

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

2つ目は、オブジェクトの宣言だけを含むスクリプトにSNIPPETを追加する方法です。スクリプトに複数のオブジェクトが渡される場合、それらをすべて1つのSNIPPETで宣言することができます。これは、スクリプト内の他のSNIPPETアクションを簡潔にするのに役立ちます。このアクションをスクリプトの他のアクションに接続する必要はありません。スクリプト内にあるだけで、スクリプトの検証時にオブジェクト宣言の要件を満たすことができます。