<ph type="x-smartling-placeholder"></ph>
您正在查看 Apigee Edge 文档。
转到
Apigee X 文档。 信息
本主题讨论如何在 API 代理中使用消息模板,并提供函数参考。
什么是消息模板?
消息模板允许您在某些政策和 TargetEndpoint 元素中执行变量字符串替换。此功能若受支持,则可让您在代理执行时动态填充字符串。
您可以将任何流变量引用和文字的任意组合包括在消息模板中。流变量名称必须用大括号括起来,而用大括号括起来的任何文本都将输出为文字。
另请参阅可在何处使用消息模板?
示例
例如,借助“分配消息”政策,您可以在 <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> <ReasonPhrase>Quota Exceeded</ReasonPhrase> </Set> </AssignMessage>
在 AssignMessage 政策中,<Set>
元素中的以下元素支持消息模板:
- 标题
- QueryParam
- FormParam
- PayLoad
- 版本
- 动词
- 路径
- StatusCode
- ReasonPhrase
另请注意,消息模板中的流变量必须用大括号括起来。
当此政策执行时:
- Header 元素会接收所指定流变量的值。
- Payload 包括文字和变量的组合(动态填充
client_id
)。 - StatusCode 和 ReasonPhrase 仅包括文字;但是,如果您想使用消息模板,这些元素也支持消息模板。
示例
在代理 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、ReasonPhrase、Headers、QueryParams、FormParams
|
ExtensionCallout 政策 |
<Input> |
ExtractVariables 政策 | <JsonPath> |
GenerateJWS 政策 VerifyJWS 政策 |
<Payload> (仅适用于 GenerateJWS 政策)
* 仅当 type=map 时,这些元素才支持消息模板。 |
GenerateJWT 政策 VerifyJWT 政策 |
<AdditionalClaims><Claim>
* 仅当 type=map 时,这些元素才支持消息模板。 |
LDAP 政策 | <SearchQuery> |
MessageLogging 政策 | <Syslog><Message>
|
OASValidation 政策 | 元素 |
RaiseFault 政策 | <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、ReasonPhrase、Headers、QueryParams、FormParams
|
SAMLAssertion 政策 | <Template>
* 仅当政策签名为 |
ServiceCallout 政策 | <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、ReasonPhrase、/Headers、QueryParams、FormParams
|
接受消息模板的 TargetEndpoint 元素
HTTPTargetConnection 元素 | 支持消息模板的子元素 |
---|---|
SSLInfo | Enabled、KeyAlias、KeyStore、TrustStore、ClientAuthEnabled、CLRStore |
LocalTargetConnection | ApiProxy、ProxyEndpoint |
路径 | 无 |
消息模板语法
本部分介绍了使用消息模板时必须遵循的规则。
使用大括号表示变量
使用 大括号 { } 括住变量名称。如果变量不存在,则会在输出中返回空字符串;但是,您可以在消息模板中指定默认值(在变量无法解析时会替换的值)。请参阅在消息模板中设置默认值。
请注意,允许使用引号将整个消息模板字符串括起来,不过此操作是可选的。例如,下面的两个消息模板是等效的:
<Set> <Headers> <Header name="x-h1">"Hello {user.name}"</Header> <Header name="x-h1">Hello {user.name}</Header> </Headers> </Set>
在消息模板中设置默认值
如果模板化变量无法解析,则 Edge 会替换空字符串。不过,您可以按如下方式指定默认值:
<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>
在上面的示例中,如果无法解析变量 request.header.id
,则其值替换为 Unknown
。例如:
Test message. id = Unknown
函数表达式中不允许有空格
消息模板函数表达式中不允许有空格。例如:
允许:
{substring(alpha,0,4)} {createUuid()} {randomLong(10)}
不允许:
{substring( alpha, 0, 4 )} { createUuid( ) } {randomLong( 10 )}
JSON 载荷的旧语法
在 Cloud 16.08.17 之前的 Edge 版本中,您无法
使用大括号来表示 JSON 载荷中的变量引用。在旧版中,您需要使用 variablePrefix
和 variableSuffix
属性来指定分隔符,并使用这些属性来封装变量名称,如下面所示:
<Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo", "type":"@variable_name#"} </Payload> </Set>
虽然 Apigee 建议您使用较新的大括号语法,但旧版语法仍然有效。
使用消息模板函数
Edge 提供了一组函数,您可以在消息模板中使用这些函数进行转义、编码、哈希处理 和格式字符串变量。
消息模板函数参考中详细介绍了消息模板函数。
示例: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." }
然后,假设您想要在自定义载荷中将此消息返回给客户端调用方。执行此操作的常用方法是从目标响应载荷中提取消息,然后使用“分配消息”将消息添加到自定义代理响应(即将消息发送回客户端)。
下面是将 user_message
信息提取到名为 standard.systemMessage
的变量的“提取变量”政策:
<ExtractVariables name="EV-BackendErrorResponse"> <DisplayName>EV-BackendErrorResponse</DisplayName> <JSONPayload> <Variable name="standard.systemMessage"> <JSONPath>$.user_message</JSONPath> </Variable> </JSONPayload> </ExtractVariables>
现在,有一个完全有效的“分配消息”政策,用于将提取的变量添加到响应载荷(代理响应):
<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>
很遗憾,出现了问题。“提取变量”政策移除了消息部分两侧的转义引号字符。这意味着,返回给客户端的响应是无效的 JSON。这显然不是您想要的结果!
{ "systemMessage": "Invalid value for "logonId" check your input." }
如需解决此问题,您可以修改“分配消息”政策,以使用会将 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)
|
采用本地时区格式返回日期。 |
timeFormatMs(format,str)
|
采用本地时区格式返回日期。 |
timeFormatUTC(format,str)
|
采用 UTC 格式返回日期。 |
timeFormatUTCMs(format,str)
|
采用 UTC 格式返回日期。 |
参数
- format - 日期/时间格式字符串。可以是文本字符串,也可以是字符串变量。
- str - 包含时间值的字符串或字符串流变量。对于 timeFormatM,此值可以 seconds-since-epoch 或 milliseconds-since-epoch。
示例
假设采用以下值并假设本地时区为 Pacific:
epoch_time_ms = 1494390266000
epoch_time = 1494390266
fmt1 = yyyy-MM-dd
fmt2 = yyyy-MM-dd HH-mm-ss
fmt3 = yyyyMMddHHmmss
这些函数会返回以下结果:
- key -(必需)指定编码为字符串的密钥,用于计算 HMAC。
- valueToSign -(必需)指定要签名的消息。它应该是字符串。
- keyencoding -(可选)密钥字符串将根据此指定的编码进行解码。有效值:
hex
、base16
、base64
、utf-8
。默认值:utf-8
- outputencoding -(可选)指定用于输出的编码算法。有效值:
hex
、base16
、base64
。值不区分大小写;hex
和base16
是同义词。默认:base64
函数 | 输出 |
---|---|
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 进行编码。 |
参数
示例
此示例使用 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 类计算出的随机长整型。
- 如果存在一个参数,则将其视为计算的最小值。
- 如果存在第二个参数,则将其视为计算的最大值。
示例
{random()}
产生类似如下的结果:
5211338197474042880
正则表达式文本生成器
生成与给定正则表达式相匹配的文本字符串。
语法
xeger(regex)
参数
regex - 正则表达式。
示例
下面的示例会生成一个不含零的 7 位数字符串:
xeger('[1-9]{7}')
示例结果:
9857253
Null 合并函数
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 -(可选)指定所需的查询返回类型。可以是节点集、节点、数字、布尔值或字符串。默认值为节点集。默认值通常是正确的选择。
示例 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
如果只需要节点的值,请使用 text()
函数,如下所示:
<AssignMessage> <AssignVariable> <Name>extracted_tag</Name> <Template>{xpath('/tag/tagid/text()',xml)}</Template> </AssignVariable> </AssignMessage>
此操作会将上下文变量 extracted_tag
设置为 250397
如果选择了多个节点,则 xpath()
的结果是选择的所有值,并以逗号串接。
示例 3: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('/tag/tagid/text()',xml)}
如果 XPath 表达式包括命名空间前缀(和冒号),则需要将 XPath 表达式分配给变量并指定变量名称,而不是直接指定表达式。
{xpath(xpathexpression,xml,ns1)}
示例 4:指定所需的返回类型
传递给 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']