オブジェクトは、1つの変数内に複数の値を保持できるデータ構造です。これはスクリプトの中で、ある"もの"に関連する値のコレクションがある場合に便利です。例えば、名前、電話番号、電子メールアドレスなど、コンタクトに関する一連のデータがあるとします。これらの値をすべて1つのオブジェクトに格納することができます。これにより、スクリプト内で使用する変数の数を減らすというメリットがあります。
Studioは、ダイナミックデータ型のオブジェクトをサポートしています。この型は、XMLやJSONのような固定フォーマットやタイプを持たないデータを扱うことができます。
Snippetコードで宣言するか、JSONやXMLを解析することで動的データオブジェクトを作成できます。また、APIコールからのレスポンスや特定のフレームワークのアクションからも作成されます。
ダイナミックデータオブジェクトは、標準の変数を使用できるすべてのStudioアクションで使用できます。ダイナミックデータオブジェクトは、標準変数と同じように、データを保持するために使用できますが、それ以外の用途もあります。例えば、これらを使って以下のことを行えます。
- REST API呼び出しを生成する。
- Workflowdataアクションからの応答を処理する。このアクションは、動的データオブジェクトでワークフローデータを返します。
スクリプト内の動的データ変数とオブジェクトの数は、トレースに影響を与える可能性があります。多くの動的変数を含むスクリプトのパフォーマンスの問題が発生する可能性があります。含まれるデータが多いほど、各アクションを処理する時間が長くなります。
ダイナミックデータオブジェクトに関する重要ポイント
- ダイナミックデータオブジェクトが保持する値はメンバーと呼ばれます。
- 各メンバーはその名前で識別されます。例えば、
- オブジェクトメンバーの型は実行時に決定されます。コンパイラはプロパティに関する情報を保存します。ランタイムにその情報が調査され、処理されます。このため、コンパイラではダイナミックデータオブジェクトのエラーが検出されません。その代わり、エラーがあるとランタイム例外が発生します。
- ダイナミックデータオブジェクトは、動的に作成されるメンバーを持つことができます。スクリプトでダイナミックデータオブジェクトを宣言した後、その後の行でオブジェクトのメンバーに値を代入します。他のスニペットでメンバーに値を割り当てることも可能です。メンバーが存在しない場合は、自動的に作成され、指定された値が割り当てられます。
- ダイナミックデータオブジェクトは多くの種類のデータを格納することができます。標準のスニペット変数は暗黙的に型指定されるので、Studioコンパイラがコードをコンパイルするときに型が決定されます。ダイナミックデータオブジェクトはダイナミックデータ型です。オブジェクトのメンバーは暗黙的に型指定されます。
- ダイナミックデータオブジェクトのメンバーを参照する際は、大文字と小文字の区別が重要です。例えば、ASSIGN fileContent = "{beowulfcharacteristics.Files.file}"でbeowulfCharacteristics.files.fileの値を解析しようとすると、何も返されません。これは、
- ダイナミックデータオブジェクトのすべてのメンバーは、
- ダイナミックデータオブジェクトとそのメンバーは32 KB未満でなければなりません。オブジェクトをJSONまたはXMLに変換する場合、変換後のコンテンツは32KB未満でなければなりません。変換されたオブジェクトの内容がその制限を超える場合、切り捨てられます。
試してみる
オブジェクトの例スクリプトをダウンロードしてStudioにインポートします。このヘルプページの例の多くは、サンプルスクリプトの
オブジェクトメンバー
ダイナミックデータオブジェクトは、プロパティ（メンバーとも呼ばれます）をキーと値のペアの形で保持します。キーはメンバーの名前で、オブジェクト内にある変数の名前のようなものです。次の例では、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の標準変数と同じ命名ガイドラインに従わなければなりません。オブジェクト名では大文字と小文字が区別されます。
メンバーを追加するには次の構文を使用します。
<objectName>.<memberName> = "value"。
メンバー名では大文字と小文字が区別されます。オブジェクトにメンバーを追加するのにキーワードを使う必要はありませんが、オプションで
ダイナミックデータオブジェクト内に配列を作成するには、次の構文を使用します。
DYNAMIC <object>
ASSIGN <object>.<member>[<index>].<sub-member>= "value"
動的データオブジェクトを宣言する
ダイナミックデータオブジェクトを宣言するには、コード内で変数名の前にキーワードのDYNAMICを使用し、これにプロパティを追加します。たとえば。
DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero"
ASSIGN beowulfCharacteristics.foe = "Grendel"
オブジェクトメンバーを宣言するのにキーワードは必要ありません。オプションとして
ダイナミックデータオブジェクトのメンバーを参照する
ダイナミックデータオブジェクトに含まれている値を使用するには、その値を保持するメンバーを参照する必要があります。次の構文を使用します：
<dynamicObjectName>.<memberName>
これは標準変数と同じ方法で使用できます。ダイナミックデータオブジェクトは、変数代入を受け入れるStudioのアクションプロパティおよびスニペットで参照することができます。
例えば、以下のオブジェクトのnameというメンバーを参照するには、beowulfCharacteristics.nameを使用します。
DYNAMIC beowulfCharacteristics
beowulfCharacteristics.name = "Beowulf"
beowulfCharacteristics.occupation= "Hero"
beowulfCharacteristics.foe = "Grendel" 特殊なオブジェクトプロパティ$value
ダイナミックデータオブジェクトは、
- 関数でオブジェクトのメンバーを使用する。例：beowulfCharacteristics.name.first.
-
オブジェクトと関数
関数は、スクリプト内で呼び出して実行できるコードのブロックです。関数を使えば、変数やオブジェクト内の値を操作することができます。関数で値を変更したり、値に関する情報を取得することができます。例えば、変数やオブジェクトメンバーの値の大文字小文字を変換する関数があります。また、配列の要素数を数えたり、値が数値かどうかを判別したりする関数もあります。
スクリプト内のダイナミックデータオブジェクトで使用できる関数がいくつも用意されています。関数を実行できるのはオブジェクトのメンバーに対してだけで、オブジェクト自体に対しては実行できません。
オブジェクトで関数を使用するには、特殊オブジェクトプロパティの
オブジェクトメンバーに対して関数を実行するには、以下の構文を使用します：
例えば
オブジェクトの値を別のオブジェクトまたは変数にコピーする
データの2つのバージョンが必要な場合は、オブジェクトが保持するデータのコピーを作成できます。これにより、もう一方に影響を与えることなく一方を変更することができます。これには、組み込み関数copy()を、次の構文で使用します。
DYNAMIC <object1>
DYNAMIC <object2>
<object1> = copy(<object2>)
データはダイナミックオブジェクトまたは標準のStudio変数にコピーできます。標準変数である場合、自動的にダイナミックオブジェクトに変換されます。
copy()関数は、参照を代入するよりも多くのシステムリソースを使用します。オブジェクトをテキスト表現に変換してからオブジェクトに戻すことにより、ディープコピーを実行します。オブジェクトに大量のデータが含まれている場合、この処理はスクリプトの動作に影響を与える可能性があります。
ダイナミックオブジェクトのサブメンバーから別のダイナミックオブジェクトのサブメンバーに値をコピーすることができます。関数copy()はサブメンバーでは機能しないので、変数を互いに等しくなるよう設定する必要があります。
DYNAMIC currentContact
currentContact.who = beowulfCharacteristics.nameダイナミックオブジェクトのサブメンバーから標準変数に値をコピーすることができます。その場合、変数は自動的にダイナミックオブジェクトに変換されます。これを防ぐには、コピーするダイナミックオブジェクトとサブメンバーの名前を二重引用符と中括弧で囲む必要があります。これにより、変数が自動的にダイナミックオブジェクトに変換されないようにします。たとえば。
ASSIGN currentContact = "{beowulfCharacteristics.foe}"オブジェクトの名前をフォーマットする代わりに、
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に変更すると、
個々のサブメンバーに参照を代入することはできません。サブメンバーの値は、あるダイナミックオブジェクトから別のダイナミックオブジェクトにコピーすることができます。これにより値が複製されます。一方の値を変更しても、もう一方の値は自動的に変更されません。
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として送信します。このタスクには、
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は、関数
動的データオブジェクトをJSONまたはXMLに変換する
ダイナミックオブジェクトの内容をJSON文字列またはXML文字列に変換できます。これにより、オブジェクト内のデータをシリアル化し、インターネットで送信できる形式にします。
これを行うには、関数asjson()またはasxml()を使用して、変換するオブジェクトを指定します。Studioでは、これをSnippetアクションか、オブジェクトから変換したデータを必要とするアクションプロパティのどちらかの2つの場所で行うことができます。
どちらの方法も同じように機能します。ただし、変換されたオブジェクトを保持する変数をSnippetに作成する利点は、変換が行われている場所を簡単に確認できることです。どのアクションがオブジェクトの変換された内容を必要とするかを知る必要はありません。
Snippetでオブジェクトを変換するには、以下の構文を使用してください。
ASSIGN varJSON="{myDynamic.asjson()}"
JSONデータまたはXMLデータが必要なStudioアクションのプロパティで、Snippetで使用した変数名を使用します。構文の例では、
アクションプロパティでオブジェクトを変換するには、アクションプロパティをオブジェクトの名前と関数asjson()またはasxml()を中括弧で囲んで設定します。例:
ダイナミックオブジェクトのすべてのメンバーは、数値やBoolean
trueとfalseの2つの値を持つデータ型。値を含め、文字列値として扱われます。文字列でない値の場合は、JSONを手動で解析して二重引用符を削除する必要があります。これは関数
ダイナミックオブジェクトの内容を表示する
デバッガーを実行する際、
- Studioで、
- 必要であればスニペットコードを追加します。
-
-
の隣にある下矢印をクリックし、ステップイン
を選択します。コードを1行ずつ確認したくない場合は、デバッグ開始アイコンをクリックします。 - ステップ
アイコンをクリックして
- すべてのコード行のステップスルーが終了した場合、またはデバッグ開始をクリックした場合、
-
コード内の任意の文字列配列または動的オブジェクトの隣にある+アイコンをクリックして、それらを展開することができます。内容が別の配列またはオブジェクトである場合、ツリーを展開し続けることで各エンティティに含まれているものを確認できます。
スクリプト検証エラーとダイナミックオブジェクト
スクリプトを保存すると、Studioがスクリプト内のすべての情報を検証します。そのチェック項目の1つとして、スクリプト内で参照されているすべてのダイナミックオブジェクトが、スクリプト内で宣言されているかどうかを確認します。Studioでは、検証対象のスクリプトで参照されるすべてのオブジェクトにオブジェクト宣言が必要です。オブジェクトが別のスクリプトで宣言され、検証中のスクリプトに渡されたとしても、エラーは発生します。スクリプト内に未宣言のオブジェクトがあると、保存時に「Function '[name]' has not been defined」というエラーが表示されます。
これを避けるには、2つの方法があります。その1つがオブジェクトを参照するスニペットに
IF TEST = 1
{
DYNAMIC dynaObject
}
DYNAMIC dynaObject.prop = 12つ目は、オブジェクトの宣言だけを含むスクリプトに