訊息範本

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本主題將說明如何在 API 代理程式中使用訊息範本，並提供函式參考資料。

什麼是訊息範本？

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

您可以在訊息範本中加入任何流程變數參照和文字的組合。Flow 變數名稱必須以大括號包住，而未以大括號包住的文字會以文字字面值輸出。

另請參閱「訊息範本的用途」

範例

舉例來說，指派訊息政策可讓您在 <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 設定中使用的特定元素。

接受訊息範本的政策

接受訊息範本的 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>

以下是有效的 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."
}

如要解決這個問題，您可以修改「指派訊息」政策，使用訊息範本函式，讓系統為您在 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>

大小寫轉換函式

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

語法

引數

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

範例

以下範例假設有下列流程變數：

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

Replace All 函式

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

語法

replaceAll(string,regex,value)

引數

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

範例

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

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

替換 First 函式

只取代字串中指定規則運算式相符項目的第一次出現。

語法

replaceFirst(string,regex,value)

引數

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

字元逸出和編碼函式

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

語法

引數

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

會產生下列結果：

時間格式函式

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

語法

引數

• format - 日期/時間格式字串。可以是字串常值或字串變數。
• str - 含有時間值的字串或字串資料流變數。對於 timeFormatMs，這個值可以以 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 政策產生五個層級的連鎖 HMAC，用於計算 AWS 簽名 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

Random Long Generator 函式

傳回隨機的長整數。

語法

randomLong(args)

引數

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

範例

{random()}

會產生類似以下的結果：

5211338197474042880

規則運算式文字產生器

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

語法

xeger(regex)

引數

regex - 規則運算式。

範例

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

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

結果範例：

9857253

空值合併函式

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

語法

firstnonnull(var1,varn)

引數

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

範例 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 路徑函式

將 JSONPath 運算式套用至 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']