データアクション用の速度マクロ

注記: この記事は、AWS Lambda、Function、Genesys Cloud、Google、Microsoft Dynamics 365、Salesforce、Web サービス、Zendesk データアクションの統合に適用されます。

データアクションの統合により、カスタムアクションを作成できます。これらのカスタムアクションには、Velocity テンプレート言語を使用するテンプレートによるリクエストの設定とレスポンスの設定が含まれます。これらのテンプレートは、Velocity マクロの範囲をサポートします。

警告: 内の入力変数または出力変数の使用をエスケープします requestTemplate, successTemplate、または requestUrlTemplate. 変数を特殊文字で適切にエスケープしないと、データアクションは実行時に失敗します。

使用esc.jsonエンコードJSON 本文内の文字列をエスケープします。見るesc.jsonエンコード。
esc.url() またはurlTool.optionalQueryParam() を使って、requestUrlTemplate またはrequestTemplate のパスまたはクエリーパラメータをエスケープします。x-www.form-urlencoded 値を使っている場合。 String-escaping library およびURL form encoding for data action を参照。

Velocityテンプレートは、次のフィールドで有効です。

requestUrlTemplate
ヘッダー
requestTemplate
successTemplate

詳細については、カスタムアクションを作成する, 要求の構成そして応答構成.

メモ： フォーマルとサイレント形式表記の比較

正式表記 : $ {variable}
変数が null の場合、正式表記は変数名を出力します。
サイレント形式表記 : $!$ {variable}
変数が null の場合、サイレント表記は空の文字列を出力します。

数学ライブラリ
文字列エスケープライブラリ
エンコード。 base64
esc.jsonエンコード
esc.jsonデコード
successTemplateUtils.firstFromArray
successTemplateUtils.moveKeysIntoArrayOfオブジェクト
urlTool.optionalQueryParam
Java 文字列メソッドマクロ
Microsoft Dynamics マクロ
Salesforce マクロ

数学ライブラリ

接頭辞: 数学

これらの計算マクロを使用して、基本的な計算を実行します。詳細については、クラス MathTool Velocity のドキュメントで説明します。

文字列エスケープライブラリ

接頭辞: Esc キー

Velocity テンプレートで文字列をエスケープするには、EscapeTool を使用します。 EscapeTool は、Java、JSON、JavaScript、HTML、XML、SQL の出力をエスケープするメソッドを提供します。 EscapeTool は、Velocity テンプレート言語の文字をエスケープするメソッドも提供します。詳細については、クラス EscapeTool Velocity のドキュメントで説明します。

特に次の方法は非常に役立ちます。

$esc.urlFormEncode() : URL フォームのコーディング規則に準拠するために文字をエスケープするには、このメソッドを使用します。この方法ではスペースが「+」としてエンコードされることに注意してください。 urlTemplate には使用されない可能性が高くなります。を参照してください。 $esc.uriEncode()方法。
ます。 url (): の別名$esc.urlFormEncode()同じ機能を備えています。
$esc.uriEncode() : このメソッドを使用して、URI (URL など) の規則に準拠するように文字をエスケープします。このメソッドは、urlTemplate 内の文字をエスケープするために使用する必要があります。このメソッドではスペースが「%20」としてエンコードされることに注意してください。
$esc.jsonEncode() : このメソッドを使用して、出力内の JSON の予約文字をエスケープします。これにより、JSON を文字列形式で保存できるようになります。
$esc.jsonString() : の別名$esc.jsonEncode()同じ機能を備えています。
$esc.jsonDecode() : このメソッドを使用して、JSON の予約文字のエスケープを解除し、元の JSON を生成します。
. d (): ドル記号 ($) を含めるには、この方法を使用します。

次の表は、さまざまなマクロの入力と出力の例を示しています。

警告: JavaScriptエンコーディングを使用しないでください。 $ esc.javascript（$ input）アクションを中断する無効なJSONを作成する可能性があります。

マクロ	入力	出力
。 java ()	彼はしませんでした`'`tは言う、 `「」`やめる！`「」`	彼はしませんでした`'`tは言う、\`「」`やめる！\`「」`
. html ()	`「」`パン`「」` ＆ `「」`バター`「」`	「パン」＆「バター」
. xml ()	`「」`パン`「」` ＆ `「」`バター`「」`	「パン」＆「バター」
. sql ()	マクヘイル`'`s海軍	マクヘイル`''`s海軍
$esc.urlFormEncode($input) またはます。 url ()	あちらこちらでこんにちは〜	こんにちは+こちら+%26+そこ~
$esc.uriEncode($input)	あちらこちらでこんにちは〜	こんにちは%20ここ%20%26%20そこ%7E
・ドル	—	$
. ハッシュ		#
. バックスラッシュ		\
。引用		`「`
.singleQuote		`{"ERROR" :{"CODE" :400000,"MESSAGE" :"ONE OF THE REQUEST INPUTS IS NOT VALID."}}`
. 感嘆符		!

エンコード。 base64

提供された文字列をBase64でエンコードする。

テンプレートの例

The encoded field is $encoding.base64(\"${first} and ${second}\")

テンプレート例の結果

入力	解決済みテンプレート
最初の = = 猫第二 = = 犬	エンコードされたフィールドは Y2F0IGFuZCBkb2c =

esc.jsonエンコード

POST、PUT、および PATH リクエストの JSON 本文を構築するときは、文字列内の予約文字をエスケープする必要があります。このマクロは、JSON エンコード規則に基づいて引用符やその他の文字をエスケープします。

注記: esc.jsonエンコードUnicode 文字を異なる方法で扱いますEscapeTool.javascript()そうです。

テンプレートの例

$esc.jsonEncode(${input.json})

エンコード例

入力	出力
{ 「フー」:「バー」 }	{\n\t\”foo\”:\”bar\”\n}
Null	Null
“”（空の文字列）	“”（空の文字列）

esc.jsonデコード

JSON エンコードされた文字列があり、それを JSON 形式で取得したい場合は、 esc.jsonDecode()大きい。このマクロは、JSON エンコードルールに基づいて引用符やその他の文字をエスケープ解除します。

テンプレートの例

$esc.jsonDecode(${input.escapedjson})

デコード例

入力	出力
{\n\t\”foo\”:\”bar\”\n}	{ 「フー」:「バー」 }

successTemplateUtils.firstFromArray

このマクロは、提供された JSON 配列文字列から最初の要素を抽出し、2つのパラメータを持ちます。抽出された値の入力配列である最初のパラメーターが必要です。配列が空のときに返される応答を指定する2番目のパラメーターはオプションであり、デフォルトでは何も返しません。配列が空でない場合、2番目のパラメーターは無視されます。

の入力が firstFromArray translationMap JSONPath を通じて抽出されたデータであり、文字列のエスケープは必要ありません。以下のテンプレート例では、 Id などの translationMap エントリから来ることができます。 「」$ .idArray「」。

テンプレートの例と結果

テンプレートの例	入力	解決済みテンプレート
$ {successTemplateUtils.firstFromArray（	ids == `「」`[1, 2, 3]`「」`	1
	ids == `「」`[{\`「」`id \`「」`：1}、{\`「」`id \`「」`：2}、{\`「」`id \`「」`：3}、{\`「」`id \`「」`：4}]`「」`	{\`「」`id \`「」`：1}
	ids == `「」`[]`「」`
	ids == `「」「」`	この入力はエラーになります。
$ {successTemplateUtils.firstFromArray（\`「」`$ {ids} \`「」`、\`「」`{}\`「」`）}	ids == `「」`[1, 2, 3]`「」`	1
	ids == `「」`[{\`「」`id \`「」`：1}、{\`「」`id \`「」`：2}、{\`「」`id \`「」`：3}、{\`「」`id \`「」`：4}]`「」`	{\`「」`id \`「」`：1}
	ids == `「」`[]`「」`	{}
	ids == `「」「」`	この入力はエラーになります。
$ {successTemplateUtils.firstFromArray（\`「」`$ {ids} \`「」`、\`「」`$ esc.quote $ esc.quote \`「」`）} *	ids == `「」`[1, 2, 3]`「」`	1
	ids == `「」`[{\`「」`id \`「」`：1}、{\`「」`id \`「」`：2}、{\`「」`id \`「」`：3}、{\`「」`id \`「」`：4}]`「」`	{\`「」`id \`「」`：1}
	ids == `「」`[]`「」`	`""`
	ids == `「」「」`	この入力はエラーになります。

* このテンプレートの例では、文字のエスケープにEscapeToolを使用しています。詳細については、文字列エスケープライブラリ.

successTemplateUtils.moveKeysIntoArrayOfオブジェクト

このマクロは、Architect と互換性のある形式にデータを変換し、2 つの必須パラメータを持ちます。最初のパラメータは、元の応答からの入力です。 2 番目のパラメータは、マクロがオブジェクトに追加するキー名で、値は元の応答からの動的フィールドです。

メモ： マクロがデータを変換できない場合、データアクションはエラーまたは空の配列を返します。

変換したデータを返すには、翻訳マップおよび成功テンプレート次の例に基づくデータアクションで使用します。

データアクションの例

"config": {
  "request": {
    "requestUrlTemplate": "https://some.website.com/with/normalized/data",
    "requestType": "GET",
    "headers": {
    },
    "requestTemplateDefault": true
  },
  "response": {
    "translationMap": {
      "entitySegmentMembershipUps": "$.*.path.to.dynamic.key"
    },
    "translationMapDefaults": {},
    "successTemplate": "{\"segments\": ${successTemplateUtils.moveKeysIntoArrayOfObjects(${entitySegmentMembershipUps})},\"segmentId\")}}"
  }
}

元の回答では、 GUID は動的キーであり、正しくフラット化できないため、アクセスできません。

元の応答が返されました

"segmentMembership": { 
  "ups": { 
    "a959c128-d6d9-4a42-a307-c5d278cfcbe2": { 
      "lastQualificationTime": "2020-11-16T03:23:31Z", 
      "status": "realized" 
    } 
  }
}

マクロは ID をオブジェクトに移動し、次のように返します。セグメントID.

マクロが応答を返しました

"segments": [
  {
    "lastQualificationTime": "2020-11-16T03:23:31Z",
    "status": "realized",
    "segmentId": "a959c128-d6d9-4a42-a307-c5d278cfcbe2"
  }
]

urlTool.optionalQueryParam

このマクロは、値が空でない限り、キーと値のペアをクエリパラメータとしてフォーマットします。それ以外の場合、マクロは空の文字列を返します。テンプレートにアンパサンド (&amp ;) を含めないでください。マクロは自動的にアンパサンドを追加します。テンプレートの例の結果を参照してください。少なくとも1つの必須クエリパラメータの後にのみマクロを使用してください。次のテンプレートの例では、必要なクエリパラメーターは .

メモ： サイレント形式表記を使用する : $!$ {variable}

テンプレートの例

amount=${input.AMOUNT}$urlTool.optionalQueryParam(\"description\", $!{input.DESCRIPTION})

テンプレート例の結果

入力	解決済みテンプレート
入力。金額 = = 30 入力。説明 = = ジャガイモ	金額 = 30 &amp ; 説明 = ジャガイモ
入力。金額 = = 30 入力。説明 = =	金額 = 30

Java 文字列メソッドマクロ

値の大文字小文字の変更や文字列からの値の抽出など、文字列変数を操作するには、Velocity テンプレートで Java 文字列メソッドを使用します。詳細については、Java 17 ドキュメントのクラス文字列を参照してください。

次の例では、 toUpperCase()メソッドは、変数 $a の文字列値を大文字に変換します。はスプリット () メソッドは、変数を文字列の配列に分割します。変数連結は、変数、変数、および変数の配列の最初の項目から値を変更します。

テンプレートの例

#set($a = ${input1.string1} )
#set($a = $a.toUpperCase() )
#set($b = ${input1.string2} )
#set($c = $b.split("\+") )
#set($d = "We are using ""${a}"" ""${b}"" ""$c[1]"" to render this." )
$d

テンプレート例の結果

入力	解決済みテンプレート
入力 string1 = 値1 入力 string2 = 値 1 + 値2	使用しています `「」`VALUE1`「」` `「」`value1 + value2`「」` `「」`value2`「」` これをレンダリングします。

Microsoft Dynamics マクロ

msdynamics.fieldSearchFilter

このマクロは、検索対象の値とフィールドのリストを指定して、検索フィルタを作成します。マクロは、リスト内の各フィールドと値を比較します。

テンプレートの例

$msdynamics.fieldSearchFilter(\"$input.EMAIL_ADDRESS\", [\"emailaddress1\", \"emailadress2\"]

テンプレート例の結果

入力	解決済みテンプレート
input.EMAIL_ADDRESS = TestMail@example.com	emailaddress1 eq `'`TestMail@example.com`'` またはemailaddress2eq `'`TestMail@example.com`'`

msdynamics.phoneNumberFilter

このマクロは、電話番号と検索するフィールドのリストを指定して、検索フィルタを作成します。このマクロは、サポートされていない文字や、+ や括弧などの数字以外の値を電話番号から取り除き、各フィールドの間に \"or \" を追加します。この検索フィルタは、電話番号を取引先企業レコードの複数の電話番号と比較する場合に便利です。

テンプレートの例

$msdynamics.phoneNumberFilter(\"$input.PHONE_NUMBER\", [\"telephone1\", \"telephone2\"])

テンプレート例の結果

入力	解決済みテンプレート
入力。PHONE_NUMBER = + 1 (555) 555-0123	電話1eq `'`+1（555）555-0123`'` またはtelephone2eq `'`+1（555）555-0123`'` またはtelephone1eq `'`15555550123`'` またはtelephone2eq `'`15555550123`'`

Salesforce マクロ

Salesforce.escReserved

このマクロは、URL で作成された Salesforce SOQL/SOSL クエリからの予約文字をエスケープします。 Salesforce は以下の文字を留保します。 ? & | ! { } [ ] ( ) ^ ~ * : \ " ' + -. このマクロは、文字が適切にエスケープされることを保証します。詳細については、 {SearchQuery} を検索します。 Salesforce のドキュメントを参照してください。

テンプレートの例

FIND {$salesforce.escReserved(${input.PHONE_NUMBER})} IN PHONE FIELDS

テンプレート例の結果

入力	解決済みテンプレート
入力。PHONE_NUMBER = = (555) 555-5555	{"ERROR" :{"CODE" :400000,"MESSAGE" :"ONE OF THE REQUEST INPUTS IS NOT VALID."}}

詳細については、統合のカスタムアクションについて。

統合の詳細については、データアクションの統合についてをご覧ください。