注意:此产品的某些方面处于 Beta 版阶段。Hybrid 安装选项是 GA。要加入 Beta 版计划,请与您的 Apigee 代表联系。

消息模板

本主题讨论如何在 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

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

在消息模板中设置默认值

如果模板中的变量无法解析,Apigee 将用空字符串替换。不过,您可以按如下方式指定默认值:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

在上面的示例中,如果无法解析变量 request.header.id,则其值替换为 Unknown。例如:

Test message. id = Unknown

JSON 载荷的旧语法

16.08.17 版本之前的 Apigee 版本中,您不能在 JSON 载荷中使用大括号表示变量引用。在旧版中,您需要使用 variablePrefixvariableSuffix 属性来指定分隔符,并使用这些属性来封装变量名称,如下面所示:

<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."
}

然后,假设您想要在自定义载荷中将此消息返回给客户端调用方。执行此操作的常用方法是从目标响应载荷中提取消息,然后使用“分配消息”将消息添加到自定义代理响应(即将消息发送回客户端)。

下面是将 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。

示例

假设采用以下值并假设本地时区为 Pacific:

  • 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

    其他函数

    创建 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)
    

    参数

    json-path - 一个 JSON Path 表达式。

    json-var - 一个包含 JSON 的流变量或字符串。

    示例

    如果消息模板如下所示:

    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