消息模板

您正在查看的是 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>

在 AssignmentMessage 政策中,<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

<Add> 子元素:Headers、QueryParams、FormParams

<AssignVariable> 子元素:<Template>

ExtensionCallout 政策 <Input>
ExtractVariables 政策 <JsonPath>
GenerateJWS 政策
VerifyJWS 政策
<Payload>(仅适用于 GenerateJWS 政策

<AdditionalHeaders><Claim>

* 仅当 type=map 时,这些元素才支持消息模板。

GenerateJWT 政策
VerifyJWT 政策
<AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* 仅当 type=map 时,这些元素才支持消息模板。

LDAP 政策 <SearchQuery>
MessageLogging 政策 <Syslog><Message>

<File><Message>

OASValidation 政策 <OASResource> 元素
RaiseFault 政策 <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、ReasonPhrase、Headers、QueryParams、FormParams

<Add> 元素:Headers、QueryParams、FormParams

SAMLAssertion 政策 <Template>

* 仅当政策签名为 <GenerateSAMLAssertion>

ServiceCallout 政策 <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、ReasonPhrase、/Headers、QueryParams、FormParams

<Add> 元素:Headers、QueryParams、FormParams

<HTTPTargetConnection>/<URL>:请注意,字符串的第一部分必须为 http 或 https。

接受消息模板的 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 载荷中的变量引用。在旧版中,您需要使用 variablePrefixvariableSuffix 属性来指定分隔符,并使用这些属性来封装变量名称,如下面所示:

<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)}

结果如下:

&quot;bread&quot; &amp; &quot;butter&quot;

时间格式函数

返回时间的字符串表示法,采用本地时区或世界协调时间 (UTC) 格式。

语法

函数 说明
timeFormat(format,str) 采用本地时区格式返回日期。
timeFormatMs(format,str) 采用本地时区格式返回日期。
timeFormatUTC(format,str) 采用 UTC 格式返回日期。
timeFormatUTCMs(format,str) 采用 UTC 格式返回日期。

参数

  • format - 日期/时间格式字符串。可以是文本字符串,也可以是字符串变量。
  • str - 包含时间值的字符串或字符串流变量。对于 timeFormatM,此值可以 seconds-since-epoch 或 milliseconds-since-epoch。

示例

假设有以下值,并假设本地时区为太平洋:

  • epoch_time_ms = 1494390266000
  • epoch_time = 1494390266
  • fmt1 = yyyy-MM-dd
  • fmt2 = yyyy-MM-dd HH-mm-ss
  • fmt3 = 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 -(可选)密钥字符串将根据此指定的编码进行解码。有效值:hexbase16base64utf-8。默认值:utf-8
    • outputencoding -(可选)指定用于输出的编码算法。有效值:hexbase16base64。值不区分大小写;hexbase16 是同义词。默认: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 类计算出的随机长整型。
    • 如果存在一个参数,则将其视为计算的最小值。
    • 如果存在第二个参数,则将其视为计算的最大值。

    示例

    {random()}
    

    生成如下内容:

    5211338197474042880
    

    正则表达式文本生成器

    生成与指定正则表达式匹配的文本字符串。

    语法

    xeger(regex)
    

    参数

    regex - 正则表达式。

    示例

    以下示例生成一个不包含 0 的 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() 函数用于 AssignmentMessage 政策,如下所示:

    <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']