訊息範本

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本主題將說明如何在 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> 的子項元素支援訊息範本。按照政策中使用的相同模式，代理伺服器執行時，大括號中的流程變數會遭到取代。

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

訊息範本語法

本節說明使用訊息範本時必須遵守的規則。

使用大括號表示變數

將變數名稱放在大括號 { } 中。如果變數不存在，輸出內容會傳回空字串；不過，您可以在訊息範本中指定預設值 (如果變數未解析，系統會代入這些值)。請參閱「在訊息範本中設定預設值」。

請注意，訊息範本字串可以加上引號，但並非必要。舉例來說，以下兩個訊息範本的作用相同：

<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 酬載中的變數參照。在舊版中，您必須使用 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>

很抱歉，發生問題。Extract Variables 政策移除了郵件部分內容周圍的逸出引號字元。這表示傳回給用戶端的回應是無效的 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>

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

雜湊函式

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

十六進位雜湊函式

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

語法

引數

字串 - 雜湊函式會採用單一字串引數，並根據該引數計算雜湊演算法。引數可以是字串常值或字串流程變數。

範例

函式呼叫：

sha256Hex('abc')

結果：

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

函式呼叫：

var str = 'abc';
sha256Hex(str)

結果：

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Base64 雜湊函式

計算雜湊值，並以 Base64 編碼值形式傳回該雜湊的字串表示法。

語法

引數

字串 - 雜湊函式會採用單一字串引數，並根據該引數計算雜湊演算法。引數可以是字串常值或字串流程變數。

範例

函式呼叫：

sha256Base64('abc')

結果：

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

函式呼叫：

var str = 'abc';
sha256Base64(str)

結果：

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

字串函式

對訊息範本中的字串執行作業。

Base64 編碼函式

使用 Base64 編碼架構編碼及解碼字串。

語法

引數

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>

大小寫轉換函式

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

語法

引數

字串 - 要轉換的字串。可以是字串常值或字串流程變數。

範例

<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 - (選用) 字串的結尾索引。如未提供，結束索引就是字串結尾。

範例

在下列範例中，假設存在這些流程變數：

以下是使用這些變數的函式呼叫結果：

「全部取代」功能

將規則運算式套用至字串，並將所有相符項目替換為替代值。

語法

replaceAll(string,regex,value)

引數

• string - 要進行替換的字串常值或字串流程變數。
• regex - 規則運算式。
• value：要用來取代字串中所有相符規則運算式的值。

範例

在下列範例中，假設存在這些流程變數：

以下是使用這些變數的函式呼叫結果：

取代 First 函式

只取代字串中第一個符合指定規則運算式的項目。

語法

replaceFirst(string,regex,value)

引數

• string - 要進行替換的字串常值或字串流程變數。
• regex - 規則運算式。
• value：用來取代字串中符合規則運算式的值。

字元逸出和編碼函式

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

語法

引數

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

使用須知

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

結果：

時間格式函式

傳回以當地時區或世界標準時間格式化的時間字串表示法。

語法

引數

• format - 日期/時間格式字串。可以是字串常值或字串變數。
• str - 包含時間值的字串或字串流程變數。如果 timeFormatMs 為 true，則值可以是以 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 - (選用) 系統會根據這個指定編碼解碼密鑰字串。有效值：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 政策，產生用於計算 AWS Signature v4 簽章的五個層級的串聯式 HMAC：

<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

Random Long Generator 函式

傳回隨機長整數。

語法

randomLong(args)

引數

• 如果未指定任何引數，函式會傳回 Java SecureRandom 類別計算出的隨機長整數。
• 如果只有一個引數，系統會將其視為計算的最小值。
• 如有第二個引數，系統會將其視為計算的最大值。

範例

{random()}

結果如下：

5211338197474042880

規則運算式文字生成工具

生成符合指定規則運算式的文字字串。

語法

xeger(regex)

引數

regex - 規則運算式。

範例

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

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

結果範例：

9857253

空值合併函式

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

語法

firstnonnull(var1,varnn>)

引數

var1 - 內容變數。

var_n - 一或多個情境變數。您可以將最右側的引數設為字串，提供備用值 (如果未設定任何左側引數，系統就會設定這個值)。

範例

下表說明如何使用函式：

範本	Var1	Var2	Var3	結果
{firstnonnull(var1,var2)}	未設定	foo	N/A	foo
{firstnonnull(var1,var2)}	foo	bar	N/A	foo
{firstnonnull(var1,var2)}	foo	未設定	N/A	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)}	未設定	N/A	N/A	null
{firstnonnull(var1)}	foo	N/A	N/A	foo
{firstnonnull(var1,var2)}	""	bar	N/A	""
{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"

AssignMessage 政策會使用 xpath() 函式，如下所示：

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