用于数据操作的 Velocity 宏

注意: 本文适用于 AWS Lambda、Genesys Cloud、Google、Microsoft Dynamics 365、Salesforce、Web 服务和 Zendesk 数据操作集成。

数据操作集成允许您创建自定义操作。 这些自定义操作包括请求配置和响应配置以及使用 Velocity 模板语言的模板。 这些模板支持一系列 Velocity 宏。

警告: 在请求 模板成功模板或 requestURLTemplate中转义对输入或输出变量的任何使用。 如果您没有正确转义带有特殊字符的变量,则数据操作在执行时会失败。
  • 使用esc.jsonEncode对 JSON 主体内的字符串进行转义。 看esc.jsonEncode
  • 如果使用 x-www.form- urlencoded 值,请使用 esc.url () 或 urlTool.optionalQueryParam () 来转义 requestURLT emplate 或 requestTemplate 的路径或查询参数。 有关数据操作,请参阅字符串转义库 URL 表单编码

Velocity 模板对以下字段有效:

  • 请求URL模板
  • 标头
  • 请求模板
  • 成功模板

有关更多信息,请参阅 创建自定义操作请求配置响应配置

注意: 正式与沉默的形式表示法

  • 形式表示法: $ {变量}

    如果变量为空,则正式表示法将输出变量名称。

  • 沉默的形式表示法: $!{变量}

    如果变量为空,则静默表示法输出空字符串。

数学库

前缀: 数学

使用这些数学宏来执行基本的数学运算。 有关更多信息,请参阅 Velocity 文档 中的 Class MathTool。

字符串转义库

前缀: esc

使用 EscapeTool 在 Velocity 模板中转义字符串。 EscapeTool 提供了转义 Java、JSON、JavaScript、HTML、XML 和 SQL 输出的方法。 EscapeTool 还提供了转义速度模板语言字符的方法。 有关更多信息,请参阅 Velocity 文档 中的 C lass EscapTool。

以下方法尤其非常有用:

  • $esc.urlFormEncode() : 使用此方法对字符进行转义以符合 URL 表单编码规则。 请注意,此方法将空格编码为“+”。 它很可能不用于 urlTemplate。 请参阅$esc.uriEncode()方法。
  • $esc.url (): 别名为$esc.urlFormEncode()具有相同的功能。
  • $esc.uriEncode() : 使用此方法转义字符以符合 URI(例如 URL)规则。 此方法应用于转义 urlTemplate 中的字符。 请注意,此方法将空格编码为“%20”。
  • $esc.jsonEncode() : 使用此方法可以转义输出中 JSON 的保留字符。 它允许 JSON 以字符串形式存储。
  • $esc.jsonString() : 别名为$esc.jsonEncode()具有相同的功能。
  • $esc.jsonDecode() : 使用此方法对 JSON 的保留字符进行转义,从而生成原始 JSON。
  • $esc.d (): 使用此方法可以包含美元符号 ($)。

下表显示了各种宏的输入和输出示例。 

警告: 不要使用 JavaScript 编码。 $esc.javascript ($ 输入) 可以创建无效的 JSON 来破坏操作。

输入 输出
$esc.java ($ 输入) 他没说 停下来! 他没说\"停下来!\
$esc.html ($ 输入) 面包黄油 “面包” 和 “黄油”
$esc.xml ($ 输入) 面包黄油 “面包” 和 “黄油”
$esc.sql ($ 输入) 麦克海尔的海军 麦克海的海军

$esc.urlFormEncode($输入)

$esc.url ($ 输入)

你好这里那里~ 你好+这里+%26+那里~

$esc.uriEncode($输入)

你好这里那里~ 你好%20这里%20%26%20那里%7E
$esc 美元 $
$esc.hash #
$esc. 反斜杠 \
$esc. 报价 "
$esc. 单引号 '
$esc。感叹号 !

编码 .base64

Base64 对您提供的字符串进行编码。 

模板名称

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

模板示例结果

输入 已解析模板

首先 == 猫

第二个 == 狗

编码的字段为 y2f0igfuzCBKb2C =

esc.jsonEncode

当您为 POST、PUT 和 PATH 请求构建 JSON 正文时,必须对任何字符串中的保留字符进行转义。 此宏根据 JSON 编码规则对引号和其他字符进行转义。

笔记: esc.jsonEncode对待 Unicode 字符的方式与EscapeTool.javascript()做。 

模板名称

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

编码示例

输入 输出

{

“foo”:“酒吧”

}

{\n\t\”foo\”:\”bar\”\n}

“”(空字符串)

“”(空字符串)

esc.json解码

当你有一个 JSON 编码的字符串并且想要它的 JSON 形式时,你可以使用esc.jsonDecode()宏。 该宏根据 JSON 编码规则对引号和其他字符进行转义。

模板名称

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

解码示例

输入 输出

{\n\t\”foo\”:\”bar\”\n}

{

“foo”:“酒吧”

}

Successtemplateutils.First 来自 Array

此宏从提供的 JSON 数组字符串中提取第一个元素,并具有两个参数。 第一个参数是必需的,它是提取的值的输入数组。 第二个参数指定当数组为空时返回的响应,它是可选的,默认情况下不返回任何内容。 如果数组不为空,则忽略第二个参数。 

如果 firstfroArray 的输入 是通过 TranslationMap jsonPath 提取的数据,则不需要字符串转义。 在以下模板示例中, id 可能来自 TranslationMap 条目,例如 id$.idArray"

模板示例和结果

模板示例 输入 已解析模板
$ {成功模板 Utils.First 来自数组 ("$ {ids}")} ids == "[1, 2, 3] 1
ids == "[{\"id\": 1}, {\"id\ ": 2}, {\" id\": 3},{\" id\": 4}] {\"id\": 1}
ids == "[]
ids == " 此输入会导致错误。
$ {成功模板 Utils.First 来自数组 (\"$ {ids}\",\"{}\")} ids == "[1, 2, 3] 1
ids == "[{\"id\": 1}, {\"id\ ": 2}, {\" id\": 3},{\" id\": 4}] {\"id\": 1}
ids == "[] {}
ids == " 此输入会导致错误。
$ {成功模板实用程序。首先来自数组 (\"$ {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.MoveKeSemplateutils.MoveKeSmove 到对象数组中

此宏将数据转换为与 Architect 兼容且具有两个必需参数的格式。 第一个参数是来自原始响应的输入。 第二个参数是宏添加到对象的键名,值是来自原始响应的动态字段。

注意: 如果宏无法转换数据,则 data 操作将返回错误或空数组。

要返回转换后的数据,请根据以下示例在数据操作 中配置 TranslationMapSuccesTemplate。

数据操作示例

"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 移动到对象中并将其作为 SegmentId 返回。 

宏返回的响应

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

urltool。可选的查询参数

除非值为空,否则此宏将键值对格式化为查询参数。 否则,宏将返回空字符串。 请勿在模板中包含 & 符号;宏会自动添加 & 符号。 请参阅模板示例结果。  只能在至少一个必需的查询参数之后使用宏。 在以下模板示例中,所需的查询参数为 $ {input.amount}

注意: 使用静默的形式表示法: $!{变量}。
模板名称

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

模板示例结果

输入 已解析模板

输入。金额 =30

输入。描述 == 土豆

金额 =30 & 描述 = 土豆

输入。金额 =30

输入。说明 == "

金额 =30

Java 字符串方法宏

在 Velocity 模板中使用 Java 字符串方法来操作字符串变量,例如更改值的大小写或从字符串中提取值。 有关更多信息,请参阅 Java 17 文档 中的 类字符串。

在下面的示例中, toUpperCase()方法将变量 $a 的字符串值转换为大写。 split () 方法将变量 $b 拆分为字符串数组。 变量 $d 将变量 $a、变量 $b 和变量 $c 的数组中第一项的值连接起来。

模板名称

#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 CRM

msDynamics.Field 搜索过滤器

此宏会在给定值和要搜索的字段列表的情况下构建搜索过滤器。 宏将该值与列表中的每个字段进行比较。

模板名称

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

模板示例结果

输入 已解析模板
输入 .email 地址 = TestMail@example.com 电子邮件地址 1 eq TestMail@example.com 或电子邮件地址 2 eq TestMail@example.com

msDynamics.电话/过滤器

此宏会在给定电话号码和要搜索的字段列表的情况下构建搜索过滤器。 宏会从电话号码中去除不受支持的字符和任何非数字值,例如 + 和括号,并在每个字段之间添加 “或”。 此搜索过滤器可用于将电话号码与帐户记录中的多个电话号码进行比较。

模板名称

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

模板示例结果

输入 已解析模板
输入。电话号码 = +1 (555) 555-0123 电话 1 eq '+1 (555) 555-0123' 或电话 2 eq '+1 (555) 555-0123' 或电话 1 eq '或电话 2 eq 15555550123' 或电话 2 eq '15555550123'

Salesforce 宏

Salesforce.ESC 保留

此宏会转义在 URL 中进行的 Salesforce SOQL/SOSL 查询中的保留字符。 Salesforce 保留以下字符: ? & | ! { } [ ] ( ) ^ ~ * : \ " ' + -. 此宏可确保正确转义字符。 有关更多信息,请参阅 Salesforce 文档 中的查 找 {searchQuery}。

模板名称

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

模板示例结果

输入 已解析模板
输入 .PHONE_Number == (555) 555-5555 在电话字段中找到 {\ (555\) 555\ -5555}

有关更多信息,请参阅 关于集成的自定义操作

有关集成的更多信息,请参阅 关于数据操作集成