本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
本主题讨论如何在 API 代理中使用消息模板，并提供函数参考。
什么是消息模板？
消息模板允许您在某些政策和 <TargetEndpoint> 元素中执行变量字符串替换。此功能若受支持，则可让您在代理执行时动态填充字符串。
您可以将任何流变量引用和文字的任意组合包括在消息模板中。流变量名称必须用大括号括起来，而用大括号括起来的任何文本都将输出为文字。
另请参阅可在何处使用消息模板？
示例
例如，借助 AssignMessage 政策，您可以在 <Payload> 元素中使用消息模板：
<AssignMessage name="set-dynamic-content"> <AssignTo createNew="false" type="response"></AssignTo> <Set> <Payload contentType="application/json"> {"name":"Alert", "message":"You entered an invalid username: {user.name}"} </Payload> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
在上面的示例中，流变量 user.name（在大括号中）的值将在运行时进行评估并代入载荷字符串。因此，例如，若是 user.name=jdoe，则载荷中生成的消息输出将是 You entered an invalid username:
jdoe。如果无法解析该变量，则会输出空字符串。
示例
超过配额时，最好向调用方返回有意义的消息。此模式通常与“故障规则”一起使用来提供输出，以向调用方提供有关配额违规的信息。在下面的 AssignMessage 政策中，消息模板用于在多个 XML 元素中动态填充配额信息：
<AssignMessage name='AM-QuotaViolationMessage'> <Description>message for quota exceeded</Description> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Set> <Headers> <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header> <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header> <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header> </Headers> <Payload contentType='application/json'>{ "error" : { "message" : "you have exceeded your quota", "clientId" : "{request.queryparam.apikey}" } } </Payload> <StatusCode>429</StatusCode> </Set> </AssignMessage>
在 AssignMessage 政策中，<Set> 元素中的以下元素支持消息模板：
<Header><QueryParam><FormParam><PayLoad><Version><Verb><Path><StatusCode>
另请注意，消息模板中的流变量必须用大括号括起来。
当此政策执行时：
<Header>元素会接收所指定流变量的值。- 载荷包括文字和变量的组合（动态填充
client_id）。 <StatusCode>仅包含字面量文本；不过，如果您想要使用该元素，该元素也支持消息模板。
示例
在代理 <TargetEndpoint> 定义中，<SSLInfo> 的子元素支持消息模板。遵循在政策中使用的相同模式，代理执行时会替换大括号中的流变量。
<TargetEndpoint name="default"> ... <HTTPTargetConnection> <SSLInfo> <Enabled>{myvars.ssl.enabled}</Enabled> <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled> <KeyStore>{myvars.ssl.keystore}</KeyStore> <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias> <TrustStore>{myvars.ssl.trustStore}</TrustStore> </SSLInfo> </HTTPTargetConnection> ... </TargetEndpoint>
可在何处使用消息模板？
多个政策以及在 TargetEndpoint 配置中使用的某些元素支持消息模板。
接受消息模板的政策
下表列出了相关政策以及支持的元素/子元素：
| 政策 | 元素/子元素 |
|---|---|
| AccessControl 政策 | <SourceAddress>（适用于 mask 属性和 IP 地址）。 |
| AssignMessage 政策 | <Set> 子元素：Payload、ContentType、Verb、Version、Path、StatusCode、Headers、QueryParams、FormParams
|
| CORS 政策 | |
| ExtractVariables 政策 | <JsonPath>
|
| GenerateJWS 政策 VerifyJWS 政策 |
* 仅当 type=map 时，这些元素才支持消息模板。 |
| GenerateJWT 政策 VerifyJWT 政策 |
<AdditionalClaims><Claim>
* 仅当 type=map 时，这些元素才支持消息模板。 |
| HTTPModifier 政策 | <Set> 子元素：
|
| MessageLogging 政策 |
|
| OASValidation 政策 | |
| RaiseFault 政策 |
|
| SAMLAssertion 政策 | <Template>
* 仅当政策签名为 |
| ServiceCallout 政策 |
|
接受消息模板的 <TargetEndpoint> 元素
<HTTPTargetConnection> 元素 |
支持消息模板的子元素 |
|---|---|
<SSLInfo> |
<Enabled>、<KeyAlias>、<KeyStore>、<TrustStore>、<ClientAuthEnabled>、<CLRStore> |
<LocalTargetConnection> |
<ApiProxy>、<ProxyEndpoint>、<Path> |
<Path> |
不适用 |
<URL> |
无子元素。如需了解用法，请参阅网址模板。 |
消息模板语法
本部分介绍了使用消息模板时必须遵循的规则。
使用大括号表示变量
使用大括号 { } 括住变量名称。如果变量不存在，则会在输出中返回空字符串；但是，您可以在消息模板中指定默认值（在变量无法解析时会替换的值）。请参阅在消息模板中设置默认值。
请注意，允许使用引号将整个消息模板字符串括起来，不过此操作是可选的。例如，下面的两个消息模板是等效的：
<Set>
<Headers>
<Header name="x-h1">"Hello {user.name}"</Header>
<Header name="x-h1">Hello {user.name}</Header>
</Headers>
</Set>函数表达式中不允许有空格
消息模板函数表达式中不允许有空格。例如：
允许：
{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}不允许：
{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}不支持使用嵌套函数
不支持在模板的一个函数中调用另一个函数。例如，您不能使用：
{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}将模板函数中的字符串字面量用英文单引号括起
在函数中提供字符串字面量时，请用英文单引号（而不是英文双引号）将字符串括起来。
例如：{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}避免在字符串字面量中使用特殊字符
避免在字符串字面量中使用特殊字符，例如“:”“/”“<”或“>”。这些字符可能会导致错误。如果字符串字面量需要特殊字符，请使用 Python 或 JavaScript 政策为变量赋值，然后在模板中使用该变量。
在消息模板中设置默认值
如果模板中的变量无法解析，Apigee 将用空字符串替换。不过，您可以按如下方式指定默认值：
<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>在上面的示例中，如果无法解析变量 request.header.id，则其值替换为 Unknown。例如：
Test message. id = Unknown
网址模板
URL 元素支持遵循与其他元素相同的语法的模板。
此示例显示了使用变量构建的网址：
<URL>{targeturl}</URL>此示例显示协议的默认值：
<URL>{protocol:https}://{site:google.com}/path</URL>JSON 载荷的旧语法
在 16.08.17 版本之前的 Apigee 版本中，您不能在 JSON 载荷中使用大括号表示变量引用。在旧版中，您需要使用 variablePrefix 和 variableSuffix 属性来指定分隔符，并使用这些属性来封装变量名称，如下面所示：
<Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo","type":"@variable_name#"} </Payload> </Set>
虽然 Apigee 建议您使用较新的大括号语法，但旧版语法仍然有效。
使用消息模板函数
Apigee 提供了一组函数，可在消息模板中使用这些函数来转义、编码、哈希处理和格式化字符串变量，如下所述。
示例：toLowerCase()
使用内置的 toLowerCase() 函数将字符串变量转换为小写：
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header> </Headers> </Set> </AssignMessage>
如果 foo.bar 流变量可以解析，则其字符将全为小写。如果 foo.bar 无法解析，则会替换为默认值 FOO 并转换为小写字符。例如：
Test header: foo
示例：escapeJSON()
下面是一个有趣的用例：假设您的后端应用返回包含有效转义字符的 JSON 响应。例如：
{
"code": "INVALID",
"user_message": "Invalid value for \"logonId\" check your input."
}然后，假设您想要在自定义载荷中将此消息返回给客户端调用方。执行此操作的常用方法是从目标响应载荷中提取消息，然后使用 AssignMessage 将消息添加到自定义代理响应（即将消息发送回客户端）。
下面是将 user_message 信息提取到名为 standard.systemMessage 的变量的 ExtractVariables 政策：
<ExtractVariables name="EV-BackendErrorResponse"> <DisplayName>EV-BackendErrorResponse</DisplayName> <JSONPayload> <Variable name="standard.systemMessage"> <JSONPath>$.user_message</JSONPath> </Variable> </JSONPayload> </ExtractVariables>
现在，有一个完全有效的 AssignMessage 政策，用于将提取的变量添加到响应载荷（代理响应）：
<AssignMessage name="AM-SetStandardFaultResponse"> <DisplayName>AM-SetStandardFaultResponse</DisplayName> <Set> <Payload contentType="application/json"> { "systemMessage": "{standard.systemMessage}" } </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
很遗憾，出现了问题。ExtractVariables 政策移除了消息部分两侧的转义引号字符。这意味着，返回给客户端的响应是无效的 JSON。这显然不是您想要的结果！
{
"systemMessage": "Invalid value for "logonId" check your input."
}如需解决此问题，您可以修改 AssignMessage 政策，以使用会将 JSON 内的引号转义的消息模板函数。此函数 escapeJSON() 将 JSON 表达式中出现的任何引号或其他特殊字符转义：
<AssignMessage name="AM-SetStandardFaultResponse"> <DisplayName>AM-SetStandardFaultResponse</DisplayName> <Set> <Payload contentType="application/json"> { "systemMessage": "{escapeJSON(standard.systemMessage)}" } </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
此函数会将嵌入的引号转义，从而产生有效的 JSON，这正是您需要的：
{
"systemMessage": "Invalid value for \"logonId\" check your input.",
}消息模板是动态字符串替换功能，您可以在特定政策和 <TargetEndpoint> 定义中使用。消息模板函数可让您在邮件模板中执行有用的操作，例如哈希、字符串操作、字符转义和其他操作。
例如，在下面的 AssignMessage 政策中，在消息模板中使用了 toLowerCase() 函数：
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Test header: {Hello,toLowerCase(user.name)}</Header> </Headers> </Set> </AssignMessage>
本部分介绍消息模板函数及其参数和输出。本主题假设您熟悉消息模板及其使用环境。
哈希函数
计算哈希值并返回该哈希的字符串表示法。
十六进制哈希函数
计算哈希值，并以十六进制数字返回该哈希的字符串表示法。
语法
| 函数 | 说明 |
|---|---|
md5Hex(string) |
计算以十六进制数字表示的 MD5 哈希。 |
sha1Hex(string) |
计算以十六进制数字表示的 SHA1 哈希。 |
sha256Hex(string) |
计算以十六进制数字表示的 SHA256 哈希。 |
sha384Hex(string) |
计算以十六进制数字表示的 SHA384 哈希。 |
sha512Hex(string) |
计算以十六进制数字表示的 SHA512 哈希。 |
参数
string：哈希函数采用单个字符串参数来计算哈希算法。该参数可以是文本字符串（用单引号括起来）或字符串流变量。
示例
函数调用：
sha256Hex('abc')结果：
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
函数调用：
var str = 'abc'; sha256Hex(str)
结果：
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
Base64 哈希函数
计算哈希值，并以 Base64 编码值的形式返回该哈希的字符串表示法。
语法
| 函数 | 说明 |
|---|---|
md5Base64(string)
|
计算以 Base64 编码值表示的 MD5 哈希。 |
sha1Base64(string)
|
计算以 Base64 编码值表示的 SHA1 哈希。 |
sha256Base64(string)
|
计算以 Base64 编码值表示的 SHA256 哈希值。 |
sha384Base64(string)
|
计算以 Base64 编码的值表示的 SHA384 哈希。 |
sha512Base64(string)
|
计算以 Base64 编码值表示的 SHA512 哈希值。 |
参数
string：哈希函数采用单个字符串参数来计算哈希算法。该参数可以是文本字符串（用单引号括起来）或字符串流变量。
示例
函数调用：
sha256Base64('abc')结果：
ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
函数调用：
var str = 'abc'; sha256Base64(str)
结果：
ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
字符串函数
对消息模板中的字符串执行操作。
Base64 编码函数
使用 Base64 编码方案对字符串进行编码和解码。
语法
| 函数 | 说明 |
|---|---|
encodeBase64(string)
|
使用 Base64 编码对字符串进行编码。例如：encodeBase64(value)，当 value 含有 abc 时，函数会返回字符串 YWJj |
decodeBase64(string)
|
对 Base64 编码的字符串进行解码。例如：decodeBase64(value)，当 value 含有 aGVsbG8sIHdvcmxk 时，函数会返回字符串 hello, world。 |
参数
string：要编码或解码的字符串。可以是文本字符串（用单引号括起来）或字符串流变量。
示例
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header> </Headers> </Set> </AssignMessage>
大小写转换函数
将字符串转换为全为大写字母或全为小写字母。
语法
| 函数 | 说明 |
|---|---|
toUpperCase(string)
|
将字符串转换为大写。 |
toLowerCase(string)
|
将字符串转换为小写。 |
参数
string：要转换的字符串。可以是文本字符串（用单引号括起来）或字符串流变量。
示例
<AssignMessage name="AM-Set-Custom-Response"> <AssignTo createNew="false" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Set> <Headers> <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header> </Headers> </Set> </AssignMessage>
Substring 函数
返回指定字符串的起始索引和结束索引之间的字符。
语法
substring(str,start_index,end_index)
参数
str：字面量字符串（用单引号括起来）或字符串流变量。start_index：该字符串的起始索引。end_index：（可选）该字符串的结束索引。如果未提供，则结束索引是字符串的结尾。
示例
对于下面的示例，假设这些流变量存在：
| 变量名称 | 值 |
|---|---|
alpha
|
ABCDEFGHIJKLMNOPQRSTUVWXYZ |
seven
|
7 |
下面是使用这些变量进行函数调用的结果：
| 消息模板表达式 | 结果 |
|---|---|
{substring(alpha,22)}
|
WXYZ
|
hello {substring(alpha,22)}
|
hello WXYZ
|
{substring(alpha,-4)}
|
WXYZ
|
{substring(alpha,-8,-4)}
|
STUV
|
{substring(alpha,0,10)}
|
ABCDEFGHIJ
|
{substring(alpha,0,seven)}
|
ABCDEFG
|
替换所有函数
将正则表达式应用于字符串，对于任何匹配项，将匹配项替换为替换值。
语法
replaceAll(string,regex,value)
参数
- string - 要在其中进行替换的文本字符串（用单引号括起来）或字符串流变量。
- regex - 正则表达式。
- value - 要替换字符串中所有正则表达式匹配项的值。
示例
对于下面的示例，假设这些流变量存在：
| 变量名称 | 值 |
|---|---|
header
|
Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
regex1
|
"^Bearer "
|
replacement
|
"TOKEN: "
|
下面是使用这些变量进行函数调用的结果：
| 消息模板表达式 | 结果 |
|---|---|
{replaceAll(header,'9993','')}
|
Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
|
{replaceAll(header,regex1,'')}
|
ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
{replaceAll(header,regex1,replacement)}
|
TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
|
替换第一个函数
仅替换字符串中所指定正则表达式匹配项的第一次出现。
语法
replaceFirst(string,regex,value)
参数
string：要在其中进行替换的文本字符串（用单引号括起）或字符串流变量。regex：正则表达式。value：要替换字符串中正则表达式匹配项的值。
字符转义和编码函数
用于对字符串中的特殊字符进行转义或编码的函数。
语法
| 函数 | 说明 |
|---|---|
escapeJSON(string)
|
反斜杠转义双引号。 |
escapeXML(string)
|
将尖括号、撇号、双引号以及和符号替换为相应的 XML 实体。用于 XML 1.0 文档。 |
escapeXML11(string) |
工作原理与 escapeXML 相同，但适用于 XML v1.1 实体。请参阅下面的“使用说明”。 |
encodeHTML(string)
|
对撇号、尖括号以及和符号进行编码。 |
参数
string：要转义的字符串。可以是文本字符串（用单引号括起来）或字符串流变量。
使用说明
XML 1.1 可以表示某些控制字符，但它不能表示 null 字节或不成对的 Unicode 代理代码点，即使在转义后也是如此。escapeXML11() 函数会移除不符合以下范围的字符：
[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
escapeXML11() 函数会转义以下范围内的字符：
[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]
示例
假设一个名为 food 的流变量具有此值："bread"
& "butter"。则函数：
{escapeHTML(food)}导致：
"bread" & "butter"
时间格式函数
返回时间的字符串表示法，采用世界协调时间 (UTC) 格式。
语法
| 函数 | 说明 |
|---|---|
timeFormat(format,str)
|
返回世界协调时间 (UTC) 格式的日期。 DEPRECATED：返回本地时区格式的日期。 |
timeFormatMs(format,str)
|
返回世界协调时间 (UTC) 格式的日期。 DEPRECATED：返回本地时区格式的日期。 |
timeFormatUTC(format,str)
|
采用 UTC 格式返回日期。 |
timeFormatUTCMs(format,str)
|
采用 UTC 格式返回日期。 |
参数
format：日期/时间格式字符串。可以是文本字符串（用单引号括起来）或字符串变量。 如果格式包含冒号，请使用变量而不是字面量。请参阅本部分中的上一条说明。str：包含时间值的字符串或字符串流变量。对于 timeFormatM，此值可以 seconds-since-epoch 或 milliseconds-since-epoch。
示例
假设采用以下值并假设本地时区为 Pacific：
epoch_time_ms = 1494390266000epoch_time = 1494390266fmt1 = yyyy-MM-ddfmt2 = yyyy-MM-dd HH-mm-ssfmt3 = yyyyMMddHHmmss
这些函数会返回以下结果：
| 函数 | 输出 |
|---|---|
timeFormatMs(fmt1,epoch_time_ms) |
2017-05-09 |
timeFormat(fmt1,epoch_time) |
2017-05-09 |
timeFormat(fmt2,epoch_time) |
2017-05-09 21:24:26 |
timeFormat(fmt3,epoch_time) |
20170509212426 |
timeFormatUTC(fmt1,epoch_time) |
2017-05-10 |
timeFormatUTC(fmt2,epoch_time) |
2017-05-10 04:24:26 |
timeFormatUTC(fmt3,epoch_time) |
20170510042426 |
HMAC 计算函数
HMAC 计算函数提供了替代使用 HMAC 政策计算 HMAC 的替代方法。执行级联 HMAC 计算时，函数非常方便，此时将一个 HMAC 的输出用作另一个 HMAC 的密钥。
语法
| 函数 | 说明 |
|---|---|
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])
|
使用 SHA-224 哈希函数计算 HMAC。 |
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])
|
使用 SHA-256 哈希函数对 HMAC 进行编码。 |
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])
|
使用 SHA-384 哈希函数对 HMAC 进行编码。 |
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])
|
使用 SHA-512 哈希函数对 HMAC 进行编码。 |
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])
|
使用 MD5 哈希函数对 HMAC 进行编码。 |
hmacSha1(key,valueToSign[,keyencoding[,outputencoding]])
|
使用 SHA-1 加密算法对 HMAC 进行编码。 |
参数
- key -（必需）指定编码为字符串的密钥，用于计算 HMAC。
- valueToSign -（必需）指定要签名的消息。它应该是字符串。
- keyencoding -（可选）密钥字符串将根据此指定的编码进行解码。有效值：
hex、base16、base64、utf-8。默认值：utf-8 - outputencoding -（可选）指定用于输出的编码算法。有效值：
hex、base16、base64。值不区分大小写；hex和base16是同义词。默认：base64
示例
此示例使用 AssignMessage 政策计算 HMAC-256 并将其分配到一个流程变量：
<AssignMessage name='AM-HMAC-1'>
<AssignVariable>
<Name>valueToSign</Name>
<Template>{request.header.apikey}.{request.header.date}</Template>
</AssignVariable>
<AssignVariable>
<Name>hmac_value</Name>
<Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
</AssignVariable>
</AssignMessage>下面的示例说明了如何生成可与 AWS Signature v4 签名流程配合使用的级联 HMAC。该示例使用 AssignMessage 政策生成级联 HMAC 的第一级，用于计算 AWS Signature v4 的签名：
<AssignMessage name='AM-HMAC-AWS-1'> <!-- 1 --> <AssignVariable> <Name>DateValue</Name> <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template> </AssignVariable> <!-- 2 --> <AssignVariable> <Name>FirstKey</Name> <Template>AWS4{private.secret_aws_access_key}</Template> </AssignVariable> <!-- 3 --> <AssignVariable> <Name>DateKey</Name> <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template> </AssignVariable> <!-- 4 --> <AssignVariable> <Name>DateRegionKey</Name> <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template> </AssignVariable> <!-- 5 --> <AssignVariable> <Name>DateRegionServiceKey</Name> <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template> </AssignVariable> <!-- 6 --> <AssignVariable> <Name>SigningKey</Name> <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template> </AssignVariable> <!-- 7 --> <AssignVariable> <Name>aws4_hmac_value</Name> <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template> </AssignVariable> </AssignMessage>
其他函数
创建 UUID 函数
生成并返回 UUID。
语法
createUuid()
参数
无。
示例
{createUuid()}示例结果：
ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8
随机长整型生成器函数
返回一个随机长整型。
语法
randomLong(args)
参数
- 如果未指定参数，此函数会返回由 Java SecureRandom 类计算出的随机长整型。
- 如果存在一个参数，则将其视为计算的最小值。
- 如果存在第二个参数，则将其视为计算的最大值。
示例
{randomLong()}产生类似如下的结果：
5211338197474042880正则表达式文本生成器
生成与给定正则表达式相匹配的文本字符串。
语法
xeger(regex)
参数
regex：正则表达式。
示例
下面的示例会生成一个不含零的 7 位数字符串：
xeger( '[1-9]{7}' )示例结果：
9857253Null 合并函数
firstnonnull() 函数会返回最左侧的非 null 参数的值。
语法
firstnonnull(var1,varn)
参数
var1：上下文变量。
varn：一个或多个上下文变量。您可以将最右侧的参数设置为字符串以提供后备值（如果未设置任何左侧参数，则会设置一个值）。
示例
下表展示了如何使用该函数：
| 模板 | Var1 | Var2 | Var3 | 结果 |
|---|---|---|---|---|
{firstnonnull(var1,var2)}
|
未设置 | foo
|
无 | foo
|
{firstnonnull(var1,var2)}
|
foo
|
bar
|
无 | foo
|
{firstnonnull(var1,var2)}
|
foo
|
未设置 | 无 | foo
|
{firstnonnull(var1,var2,var3)}
|
foo
|
bar
|
baz
|
foo
|
{firstnonnull(var1,var2,var3)}
|
未设置 | bar
|
baz
|
bar
|
{firstnonnull(var1,var2,var3)}
|
未设置 | 未设置 | baz
|
baz
|
{firstnonnull(var1,var2,var3)}
|
未设置 | 未设置 | 未设置 | null
|
{firstnonnull(var1)}
|
未设置 | 无 | 无 | null
|
{firstnonnull(var1)}
|
foo
|
无 | 无 | foo
|
{firstnonnull(var1,var2)}
|
""
|
bar
|
无 | ""
|
{firstnonnull(var1,var2,'fallback value')}
|
null
|
null
|
fallback value
|
fallback value
|
XPath 函数
将 XPath 表达式应用于 XML 变量。
语法
xpath(xpath_expression,xml_string[,datatype])
参数
xpath_expression：XPath 表达式。
xml_string：包含 XML 的流变量或字符串。
datatype：（可选）指定所需的查询返回值类型。有效值为 nodeset、node、number、boolean 或 string。默认值为 nodeset。默认值通常是正确的选择。
示例 1
假设这些上下文变量定义了 XML 字符串和 XPath 表达式：
xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>" xpath = "/tag/tagid"
xpath() 函数在 AssignMessage 政策中使用，如下所示：
<AssignMessage>
<AssignVariable>
<Name>extracted_tag</Name>
<Template>{xpath(xpath,xml)}</Template>
</AssignVariable>
</AssignMessage>
该函数会返回值 <tagid>250397</tagid>。此值放置在名为 extracted_tag 的上下文变量中。
示例 2：XML 命名空间
如需指定命名空间，请附加其他参数，每个参数都是类似于 prefix:namespaceuri 的字符串。例如，用于选择 SOAP 正文的子元素的 xpath() 函数可能如下所示：
<AssignMessage> <AssignVariable> <Name>soapns</Name> <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value> </AssignVariable> <AssignVariable> <Name>xpathexpression</Name> <Value>/soap:Envelope/soap:Body/*</Value> </AssignVariable> <AssignVariable> <Name>extracted_element</Name> <Template>{xpath(xpathexpression,xml,soapns)}</Template> </AssignVariable> </AssignMessage>
对于其他命名空间，您最多可以向 xpath() 函数添加 10 个其他参数。
使用变量在函数中包含该字符串，而不是将含有特殊字符的 XPath 表达式指定为字符串字面量。如需了解详情，请参阅避免在字符串字面量中使用特殊字符。
{xpath(xpathexpression,xml,ns1)}示例 3：指定所需的返回类型
传递给 xpath() 函数的第三个可选参数指定了查询所需的返回类型。
某些 XPath 查询可以返回数字或布尔值。例如，count() 函数会返回一个数字。下面是一个有效的 XPath 查询：
count(//Record/Fields/Pair)
下面这个有效的查询返回一个布尔值：
count(//Record/Fields/Pair)>0
在这些情况下，可以使用指定该类型的第三个参数调用 xpath() 函数：
{xpath(expression,xml,'number')}
{xpath(expression,xml,'boolean')}如果第三个参数包含冒号，则会其解读为命名空间参数。如果没有冒号，则会将其视为所需的返回值类型。在这种情况下，如果第三个参数不是有效值之一（不区分大小写），则 xpath() 函数会默认返回节点集。
JSON 路径函数
将 JSON 路径表达式应用于 JSON 变量。
语法
jsonPath(json-path,json-var,want-array)
参数
- （必需）
json-path：（字符串）JSON 路径表达式。 - （必需）
json-var：（字符串）包含 JSON 的流变量或字符串。 - （可选）
want-array：（字符串）如果此参数设置为'true'且结果集是数组，则返回所有数组元素。如果设置为任何其他值或省略此参数，则仅返回结果集数组的第 0 个元素。如果结果集不是数组，则会忽略第三个参数（如果存在）。
示例 1
如果消息模板如下所示：
The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}
且 the_json_variable 包含：
{ "results" : [ { "address" : { "line1" : "18250 142ND AV NE", "city" : "Woodinville", "state" : "Washington", "zip" : "98072" }, "name" : "Fred Meyer" }, { "address" : { "line1" : "1060 West Addison Street", "city" : "Chicago", "state" : "Illinois", "zip" : "60613" }, "name" : "Mae West" } ] }
该函数的结果为：
The address is 1060 West Addison Street
请注意，在本例中，结果集是单个元素（而不是元素数组）。如果结果集是数组，则仅返回数组的第 0 个元素。如需返回完整数组，请调用 'true' 作为第三个参数的函数，如下例所示。
示例 2
如果消息模板如下所示：
{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}
且 the_json_variable 包含：
{
"results" : [
{
"config": {
"quota": [
{
"appname": "A",
"operation": "ManageOrder",
"value": "900"
},
{
"appname": "B",
"operation": "ManageOrder",
"value": "1000"
},
{
"appname": "B",
"operation": "SubmitOrder",
"value": "800"
}
]
}
}
]
} 该函数的结果为：
['A','B']