消息模板

本页面适用于 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 配置中使用的某些元素支持消息模板。

注意：您还可以参阅政策文档，了解哪项政策和 <TargetEndpoint> 元素支持消息模板。

接受消息模板的政策

下表列出了相关政策以及支持的元素/子元素：

政策	元素/子元素
AccessControl 政策	`<SourceAddress>`（适用于 `mask` 属性和 IP 地址）。
AssignMessage 政策	`<Set>` 子元素：Payload、ContentType、Verb、Version、Path、StatusCode、Headers、QueryParams、FormParams `<Add>` 子元素：Headers、QueryParams、FormParams `<AssignVariable>` 子元素：`<Template>`
CORS 政策	`<AllowHeaders>` `<AllowMethods>` `<AllowOrigins>` `<ExposeHeaders>`
ExtractVariables 政策	`<JsonPath>` 注意：`<XMLPath>` 不接受消息模板。
GenerateJWS 政策 VerifyJWS 政策	`<Payload>`（仅适用于 GenerateJWS 政策） `<AdditionalHeaders><Claim>` * 仅当 type=map 时，这些元素才支持消息模板。
GenerateJWT 政策 VerifyJWT 政策	`<AdditionalClaims><Claim>` `<AdditionalHeaders><Claim>` * 仅当 type=map 时，这些元素才支持消息模板。
HTTPModifier 政策	`<Set>` 子元素： `<ContentType>` `<Verb>` `<Version>` `<Path>` `<StatusCode>` `<Headers>` `<QueryParams>` `<FormParams>` `<Add>` 子元素： `<Headers>` `<QueryParams>` `<FormParams>`
MessageLogging 政策	`<CloudLogging><Message>` `<Syslog><Message>` `<File><Message>`
OASValidation 政策	`<OASResource>` 元素
RaiseFault 政策	`<Set>` 元素： `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` `<Add>` 元素： `<FormParams>` `<Headers>` `<QueryParams>`
SAMLAssertion 政策	`<Template>` * 仅当政策签名为 `<GenerateSAMLAssertion>` 时
ServiceCallout 政策	`<Set>` 元素： `<ContentType>` `<FormParams>` `<Headers>` `<QueryParams>` `<StatusCode>` `<Path>` `<Payload>` `<Verb>` `<Version>` `<Add>` 元素： `<FormParams>` `<Headers>` `<QueryParams>` `<HTTPTargetConnection>/<URL>`：请参阅网址模板。

接受消息模板的 `<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 文档。对于 XML1.0 文档使用 escapeXML，对于 XML 1.1 文档使用 escapeXML11。
`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)`	返回世界协调时间 (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 = 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 -（可选）密钥字符串将根据此指定的编码进行解码。有效值：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}' )

示例结果：

Null 合并函数

firstnonnull() 函数会返回最左侧的非 null 参数的值。

语法

firstnonnull(var1,var_n)

参数

var1：上下文变量。

var_n：一个或多个上下文变量。您可以将最右侧的参数设置为字符串以提供后备值（如果未设置任何左侧参数，则会设置一个值）。

示例

下表展示了如何使用该函数：

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

消息模板

什么是消息模板？

示例

示例

示例

可在何处使用消息模板？

接受消息模板的政策

接受消息模板的 <TargetEndpoint> 元素

消息模板语法

使用大括号表示变量

函数表达式中不允许有空格

不支持使用嵌套函数

将模板函数中的字符串字面量用英文单引号括起

避免在字符串字面量中使用特殊字符

在消息模板中设置默认值

网址模板

JSON 载荷的旧语法

使用消息模板函数

示例：toLowerCase()

示例：escapeJSON()

哈希函数

十六进制哈希函数

语法

参数

示例

Base64 哈希函数

语法

参数

示例

字符串函数

Base64 编码函数

语法

参数

示例

大小写转换函数

语法

参数

示例

Substring 函数

语法

参数

示例

替换所有函数

语法

参数

示例

替换第一个函数

语法

参数

字符转义和编码函数

语法

参数

使用说明

示例

时间格式函数

语法

参数

示例

HMAC 计算函数

语法

参数

示例

其他函数

创建 UUID 函数

语法

参数

示例

随机长整型生成器函数

语法

参数

示例

正则表达式文本生成器

语法

参数

示例

Null 合并函数

语法

参数

示例

XPath 函数

接受消息模板的 `<TargetEndpoint>` 元素