您正在查看 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
|
額外資訊摘要政策 |
<Input> |
擷取變數政策 | <JsonPath>
|
GenerateJWS 政策 VerifyJWS 政策 |
<Payload> (僅限 GenerateJWS 政策)
* 這些元素只有在 type=map 時支援訊息範本。 |
GenerateJWT 政策 VerifyJWT 政策 |
<AdditionalClaims><Claim>
* 這些元素只有在 type=map 時支援訊息範本。 |
LDAP 政策 | <SearchQuery> |
MessageLogging 政策 | <Syslog><Message>
|
OASValidation 政策 | 元素 |
riseFault 政策 | <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、Reasonphrase、Headers、QueryParams、FormParams
|
SAMLAssertion 政策 | <Template>
* 只有在政策簽名為 |
服務摘要政策 | <Set> 元素:Payload、ContentType、Verb、Version、Path、StatusCode、Reasonphrase、/Headers、QueryParams、FormParams
|
接受訊息範本的 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 酬載中的變數參照。在這些舊版中,您需要使用 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." }
如要解決這個問題,您可以修改 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)}
結果:
"bread" & "butter"
時間格式函式
以字串形式傳回時間,並採用當地時區或世界標準時間。
語法
功能 | 說明 |
---|---|
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
函式會傳回下列結果:
- key - (必要) 指定以字串編碼的密鑰,用來計算 HMAC。
- valueToSign - (必填) 指定要簽署的訊息。此應為字串。
- keyencoding - (選用) 系統會根據這個指定的編碼,對密鑰字串進行解碼。有效值:
hex
、base16
、base64
、utf-8
。預設值:utf-8
- outputencoding - (選用) 指定用於輸出的編碼演算法。有效值:
hex
、base16
、base64
。值不區分大小寫;hex
和base16
為同義詞。預設值:base64
函式 | 輸出結果 |
---|---|
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 編碼。 |
引數
範例
以下範例使用 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']