本頁面由 Cloud Translation API 翻譯而成。

訊息範本

查看 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>` 子元素：Payload、ContentType、Verb、Version、Path、StatusCode、Reasonphrase、Headers、QueryParams、FormParams `<Add>` 子元素：Headers、QueryParams、FormParams `<AssignVariable>` 子元素：`<Template>`
額外資訊摘要政策	`<Input>`
ExtractVariables 政策	`<JsonPath>` `<XMLPath>` 不接受訊息範本。
GenerateJWS 政策 VerifyJWS 政策	`<Payload>` (僅限產生 JWS 政策) `<AdditionalHeaders><Claim>` * 這些元素只有在 type=map 時才支援訊息範本。
產生 JWT 政策 VerifyJWT 政策	`<AdditionalClaims><Claim>` `<AdditionalHeaders><Claim>` * 這些元素只有在 type=map 時才支援訊息範本。
LDAP 政策	`<SearchQuery>`
MessageLogging 政策	`<Syslog><Message>` `<File><Message>`
OASValidation 政策	`<OASResource>` 個元素
flaFault 政策	`<Set>` 元素：Payload、ContentType、Verb、版本、路徑、StatusCode、Reasonphrase、Headers、QueryParams、FormParams `<Add>` 元素：Headers、QueryParams、FormParams
SAMLAssertion 政策	`<Template>` * 僅限政策簽章為 `<GenerateSAMLAssertion>` 時
服務摘要政策	`<Set>` 元素：Payload、ContentType、Verb、版本、路徑、StatusCode、Reasonphrase、/Headers、QueryParams、FormParams `<Add>` 元素：Headers、QueryParams、FormParams `<HTTPTargetConnection>/<URL>`：請注意，字串的第一個部分必須是 http 或 https。

接受訊息範本的 TargetEndpoint 元素

HTTPTargetConnection 元素	支援訊息範本的子元素
SSLInfo	已啟用、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 16.08.17 版之前之前，無法使用大括號表示 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."
}

然後，假設您想在自訂酬載中，將這則訊息傳回給用戶端的呼叫端。常見的做法是從目標回應酬載中擷取訊息，然後使用「指派訊息」將其加到自訂 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>

現在，以下是一個完全有效的「指派訊息」政策，可將擷取的變數新增至回應酬載 (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."
}

如要解決這個問題，您可以修改「指派訊息」政策，使用訊息範本函式，為您逸出 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.",
}

訊息範本是一種動態字串替換功能，可用於某些政策和。訊息範本函式可讓您執行實用作業，例如雜湊、字串操縱、字元逸出等。

舉例來說，在以下 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>

本主題說明訊息範本函式、其引數和輸出內容。本主題假設熟悉訊息內容範本和使用情境

函式呼叫無法建立巢狀結構。舉例來說，您無法執行下列操作：

{substring({timeFormat("yyyy-MM-dd","1494390266")},0,4)}

雜湊函式

計算雜湊值，並傳回該雜湊的字串表示法。

十六進位雜湊函式

計算雜湊值，並以十六進位數字傳回該雜湊的字串表示法。

語法

功能	說明
`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 編碼字串解碼。例如：當 `value` 保留時 `decodeBase64(value)` `aGVsbG8sIHdvcmxk`，函式會傳回 `hello, world` 字串。

引數

字串 - 要編碼或解碼的字串。可以是常值字串或字串資料流變數。

範例

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

引數

字串 - 要替換的常值字串或字串流程變數。
regex：規則運算式。
值 - 用來取代字串內所有規則運算式相符項目的值。

範例

在以下範例中，假設有這些流程變數：

變數名稱	值
`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)

引數

字串 - 要替換的常值字串或字串流程變數。
regex：規則運算式。
值 - 要用來取代字串內規則運算式相符項目的值。

字元逸出和編碼函式

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

語法

功能	說明
escapeJSON(字串)	反斜線逸出字元則是雙引號。
escapeXML(字串)	將角括號、單引號、雙引號和 & 符號替換成各自的 XML 實體。適用於 XML 1.0 文件。如果是 XML1.0 文件，請使用 escapeXML，XML 1.1 文件則使用 escapeXML11。
escapeXML11(字串)	運作方式與 escapeXML 相同，但適用於 XML v1.1 實體。請參閱下方的使用注意事項。
encodeHTML(字串)	為單引號、角括號和 & 符號進行編碼。

引數

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

使用須知

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

結果如下：

"bread" & "butter"

時間格式函式

以字串形式傳回時間，採用當地時區或 UTC。

語法

功能	說明
`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 - (選用) 密鑰字串會據此解碼指定的編碼。有效值：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>

這個範例說明如何產生串聯 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)

引數

regex：規則運算式。

範例

這個範例會產生不含零的 7 位數字串：

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

結果範例：

空值凝結函式

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

語法

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、節點、數字、布林值、字串。並預設為 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。例如，選取某個 xpath() 函式 SOAP 主體的子項元素可能會如下所示：

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