訊息範本

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

本主題討論如何在 API Proxy 中使用訊息範本,並提供函式參考資料。

什麼是訊息範本?

訊息範本可讓您在特定政策和 TargetEndpoint 元素中執行變數字串替換。在支援這項功能的情況下,這項功能可讓您在 Proxy 執行時動態填入字串。

您可以在訊息範本中加入任何流程變數參照和常值文字組合。流程變數名稱前後必須用大括號括住,不含大括號的任何文字都會輸出為常值。

另請參閱「哪裡可以使用郵件範本?

範例

舉例來說,「指派訊息」政策可讓你在 <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。如果無法解析變數,則會輸出空字串。

範例

超過配額時,建議您傳回有意義的訊息給呼叫端。此模式經常與「錯誤規則」搭配使用,以提供輸出,讓呼叫端瞭解有關配額違規的資訊。下列「指派訊息」政策中,訊息範本的用途是在數個 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

再次提醒您,訊息範本中的流程變數必須置於大括號內

這項政策執行時:

  • 標頭元素會接收指定流程變數的值。
  • 酬載包含文字文字和變數的混合 (client_id 會動態填入)。
  • StatusCode 和 Reasonphrase 只包含文字文字;不過,如果您想使用訊息範本,這些元素也可以支援訊息範本。

範例

在 Proxy TargetEndpoint 定義中,<SSLInfo> 的子項元素支援訊息範本。執行 Proxy 時,系統會替換大括號內的流程變數 (如同政策中使用的模式)。

<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> 子元素:酬載、ContentType、Verb、Version、Path、StatusCode、Reasonphrase、Headers、QueryParams、FormParams

<Add> 子元素:標頭、QueryParams、FormParams

<AssignVariable> 子元素:<Template>

額外資訊摘要政策 <Input>
擷取變數政策 <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> 元素
riseFault 政策 <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、Reasonphrase、Headers、QueryParams、FormParams

<Add> 元素:標頭、QueryParams、FormParams

SAMLAssertion 政策 <Template>

* 只有在政策簽名為 <GenerateSAMLAssertion> 的情況下

服務摘要政策 <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、Reasonphrase、/Headers、QueryParams、FormParams

<Add> 元素:標頭、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 酬載的舊版語法

在 Edge Cloud 版本 16.08.17 之前中,您不能使用大括號來表示 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."
}

然後,假設您想在自訂酬載中將這則訊息傳回給用戶端呼叫端,一般做法是從目標回應酬載中擷取訊息,然後使用「指派訊息」將訊息新增至自訂 Proxy 回應 (也就是將訊息傳回用戶端)。

以下是「擷取變數」政策,可將 user_message 資訊擷取至名為 standard.systemMessage 的變數:

<ExtractVariables name="EV-BackendErrorResponse">
    <DisplayName>EV-BackendErrorResponse</DisplayName>
    <JSONPayload>
        <Variable name="standard.systemMessage">
            <JSONPath>$.user_message</JSONPath>
        </Variable>
    </JSONPayload>
</ExtractVariables>

現在是完全有效的「Assign Message」政策,將已擷取的變數新增至回應酬載 (Proxy 回應):

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

如要解決這個問題,您可以修改 Assign Message 政策,改用訊息範本函式,在 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 - Hash 函式會使用單一字串引數,用於計算雜湊演算法。引數可以是常值字串或字串流程變數。

範例

函式呼叫:

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 - Hash 函式會使用單一字串引數,用於計算雜湊演算法。引數可以是常值字串或字串流程變數。

範例

函式呼叫:

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 編碼的字串進行解碼。例如:如果 value 包含 aGVsbG8sIHdvcmxk,函式會傳回 hello, world 字串。decodeBase64(value)

引數

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>

Case 轉換函式

將字串轉換為全部大寫或全部小寫。

語法

功能 說明
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(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 - 要用於替代的常值字串或字串流程變數。
  • 規則運算式 - 規則運算式。
  • 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 - 要用於替代的常值字串或字串流程變數。
  • 規則運算式 - 規則運算式。
  • - 字串中要取代規則運算式比對的值。

字元逸出與編碼函式

逸出或編碼字串中的特殊字元的函式。

語法

功能 說明
EscapeJSON(字串) 反向斜線逸出會雙引號。
EscapeXML(字串) 將角括號、單引號、雙引號和 & 符號替換成個別的 XML 實體。用於 XML 1.0 文件。

EscapeXML11(字串) 運作方式與 EscapeXML 相同,但適用於 XML v1.1 實體。請參閱下方的使用注意事項。
EncodeHTML(string) 對單引號、角括號和 & 進行編碼。

引數

string - 要逸出的字串。可以是常值字串或字串流程變數。

使用須知

XML 1.1 可代表特定控製字元,但不能代表空值位元組或未配對的萬國碼 (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;

時間格式函式

以字串形式傳回時間,並採用當地時區或世界標準時間。

語法

功能 說明
timeFormat(format,str) 傳回採用當地時區的日期格式。
timeFormatMs(format,str) 傳回採用當地時區的日期格式。
timeFormatUTC(format,str) 傳回採用世界標準時間格式的日期。
timeFormatUTCMs(format,str) 傳回採用世界標準時間格式的日期。

引數

  • format - 日期/時間格式字串。可以是常值字串或字串變數。
  • str - 包含時間值的字串或字串流程變數。這個值可以是 timeFormatMs 的秒數,

範例

假設下列值,且假設當地時區是太平洋:

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

    這個範例說明如何產生階層式 HMAC,可與 AWS Signature v4 簽署程序搭配使用。這個範例會使用 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)
    

    引數

    規則運算式 - 規則運算式。

    範例

    以下範例會產生一個不加零的七位數字串:

    xeger('[1-9]{7}')
    

    搜尋結果範例:

    9857253
    

    空值耦合功能

    firstnonnull() 函式會傳回最左側非空值引數的值。

    語法

    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。預設值通常是正確的選項。

    範例 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',且結果集是陣列,則會傳回所有陣列元素。如果設為任何其他值或省略這個參數,系統只會傳回結果集陣列中的第零個元素。如果結果集不是陣列,系統會忽略這個第三個參數 (如果有的話)。

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

    請注意,在此範例中,結果集是單一元素 (不是元素陣列)。如果結果集是陣列,則只會傳回第零個陣列元素。如要傳回完整的陣列,請使用 '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']