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

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

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

警告:  内の入力変数または出力変数の使用をエスケープします requestTemplate, successTemplate、または requestUrlTemplate. 変数を特殊文字で適切にエスケープしないと、データアクションは実行時に失敗します。
  • 使用する esc.jsonString JSON本体内の文字列をエスケープします。 見る esc.jsonString.
  • esc.url() またはurlTool.optionalQueryParam() を使って、requestUrlTemplate またはrequestTemplate のパスまたはクエリーパラメータをエスケープします。x-www.form-urlencoded 値を使っている場合。 見る 文字列エスケープライブラリ.

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

  • requestUrlTemplate
  • ヘッダー
  • requestTemplate
  • successTemplate

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

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

  • 正式表記 : $ {variable}

    変数が null の場合、正式表記は変数名を出力します。

  • サイレント形式表記 : $!$ {variable}

    変数が null の場合、サイレント表記は空の文字列を出力します。

数学ライブラリ

接頭辞: 数学

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

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

接頭辞: Esc キー

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

特に2つの方法が役に立ちます。

  • ます。 url (): UrlTemplate の引数の値をエスケープするには、このメソッドを使用します。 それ以外の場合は、スペースまたはその他の非 URL 文字を含む Url は無効です。 
  • . d (): URL にドル記号 ($) を含めるには、このメソッドを使用します。

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

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

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

エンコード。 base64

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

テンプレートの例

エンコードされたフィールドは$ encoding.base64（\「」$ {first}と$ {second} \「」）。

テンプレート例の結果

入力 解決済みテンプレート

最初の = = 猫

第二 = = 犬

 エンコードされたフィールドは Y2F0IGFuZCBkb2c =

esc jsonString

POST、PUT、および PATH 要求のための JSON ボディを作成するときは、任意の文字列をエスケープする必要があります。 このマクロは、JSON エンコード規則に基づいて引用符やその他の文字をエスケープします。

 メモ：   esc jsonString Unicode 文字を異なる方法で扱います。 EscapeTool () は。 

テンプレートの例

$ esc.jsonString（$ {input.json}）

テンプレート例の結果

入力 解決済みテンプレート
これは{埋め込みタブ}を含む文字列です。 「」、および{埋め込まれた改行}、およびキリル文字 「」これは\\ t、\\\の文字列です「」、および\\ n、およびキリル文字「」
 メモ：   文字列内の Unicode 文字は JSON エンコーディング仕様では 規格 or 標準 であるため、Unicode 文字は フォーム。

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 番目のパラメータは、マクロがオブジェクトに追加するキー名で、値は元の応答からの動的フィールドです。

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

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

データアクションの例

「設定」： {{
 "リクエスト"： {{
 "requestUrlTemplate"： 「https://some.website.com/with/normalized/data」、
 "リクエストの種類"： "得る"、
 「ヘッダー」： {{
 }、
 "requestTemplateDefault"： false
  }、
 "応答"： {{
 "translationMap"： {{
 "entitySegmentMembershipUps"： "$。*。path.to.dynamic.key"
 }、
 "translationMapDefaults"： {}、
 "successTemplate"： "{\"セグメント\ "： $ {successTemplateUtils.moveKeysIntoArrayOfObjects（$ {entitySegmentMembershipUps}）}、\ "segmentId \"）}} "
 }
 }

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

元の応答が返されました

「segmentMembership」： {{
 "UPS"： {{
 "a959c128-d6d9-4a42-a307-c5d278cfcbe2"： {{
 "lastQualificationTime"： 「2020-11-16T03：23：31Z」、
 "状態"： "気がついた"
 }
 }
 }

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

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

「セグメント」： [
 {{
 "lastQualificationTime"： 「2020-11-16T03：23：31Z」、
 "状態"： "気がついた"、
 "segmentId"： 「a959c128-d6d9-4a42-a307-c5d278cfcbe2」
 }
 ]

urlTool.optionalQueryParam

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

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

amount = $ {input.AMOUNT} $ urlTool.optionalQueryParam（\「」説明\「」、$！入力。説明 = =

テンプレート例の結果

入力 解決済みテンプレート

入力。金額 = = 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 = 「」使用しています 「」「」$ {a}「」「」 「」「」$ {b}「」「」 「」「」$ c [1]「」「」 これをレンダリングします。」 ）。
 $ 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 \「」、[\「」電話1 \「」、\「」電話2 \「」]）

テンプレート例の結果

入力 解決済みテンプレート
入力。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 のドキュメントを参照してください。

テンプレートの例

電話フィールドで{$ salesforce.escReserved（$ {input.PHONE_NUMBER}）}を検索

テンプレート例の結果

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

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

統合の詳細については、 データアクションの統合について.