本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
本主題將說明如何在 API Proxy 中使用訊息範本，並提供函式參考資料。
什麼是訊息範本？
訊息範本可讓您在特定政策和 <TargetEndpoint> 元素中執行變數字串替換。這項功能 (適用於支援的平台) 可讓您在 Proxy 執行時動態填入字串。
您可以在訊息範本中加入任何流程變數參照和文字組合。流程變數名稱必須以大括號括住，而大括號以外的任何文字都會輸出為字面文字。
另請參閱「訊息範本的適用範圍」。
範例
舉例來說，AssignMessage 政策可讓您在 <Payload> 元素中使用訊息範本：
<AssignMessage name="AM-set-payload-with-dynamic-content"> <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。如果無法解析變數，系統會輸出空白字串。
範例
超過配額時，建議傳回有意義的訊息給呼叫者。這個模式通常會搭配「錯誤規則」使用，提供輸出內容，讓呼叫端瞭解配額違規情形。在下列 AssignMessage 政策中，訊息範本用於在多個 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> </Set> </AssignMessage>
在 AssignMessage 政策中，<Set> 元素中的下列元素支援訊息範本：
<Header><QueryParam><FormParam><PayLoad><Version><Verb><Path><StatusCode>
再次提醒，訊息範本中的流程變數必須以大括號括住。
這項政策執行時：
<Header>元素會收到指定流程變數的值。- 酬載包含常值文字和變數 (
client_id會動態填入)。 <StatusCode>只包含字面文字，但如果您想使用這個元素，也可以支援訊息範本。
範例
在 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>接受訊息範本的政策
下表列出政策，以及支援的元素/子元素：
| 政策 | 元素/子元素 |
|---|---|
| AccessControl 政策 | <SourceAddress>，適用於 mask 屬性和 IP 位址。 |
| AssignMessage 政策 | <Set> 子元素：Payload、ContentType、Verb、Version、Path、StatusCode、Headers、QueryParams、FormParams
|
| CORS 政策 | |
| ExtractVariables 政策 | <JsonPath>
|
| GenerateJWS 政策 VerifyJWS 政策 |
* 只有在 type=map 時，這些元素才支援訊息範本。 |
| GenerateJWT 政策 VerifyJWT 政策 |
<AdditionalClaims><Claim>
* 只有在 type=map 時，這些元素才支援訊息範本。 |
| HTTPModifier 政策 | <Set> 子元素：
|
| MessageLogging 政策 |
|
| OASValidation 政策 | |
| RaiseFault 政策 |
|
| SAMLAssertion 政策 | <Template>
* 僅限政策簽名為 |
| 服務說明文字政策 |
|
<TargetEndpoint>
接受訊息範本的元素
<HTTPTargetConnection> 元素 |
支援訊息範本的子項元素 |
|---|---|
<SSLInfo> |
<Enabled>、<KeyAlias>、<KeyStore>、
<TrustStore>、<ClientAuthEnabled>、
<CLRStore>
|
<LocalTargetConnection> |
<ApiProxy>、<ProxyEndpoint>、<Path> |
<Path> |
不適用 |
<URL> |
沒有子元素。如需使用方式，請參閱「網址範本」。 |
訊息範本語法
本節說明使用訊息範本時必須遵守的規則。
使用大括號表示變數
將變數名稱放在大括號 { } 中。如果變數不存在，輸出內容會傳回空字串；不過，您可以在訊息範本中指定預設值 (如果變數未解析，系統會代入這些值)。請參閱「在訊息範本中設定預設值」。
請注意，您可以在整個訊息範本字串加上引號，但這並非必要。舉例來說，以下兩個訊息範本是相等的：
<Set>
<Headers>
<Header name="x-h1">"Hello {user.name}"</Header>
<Header name="x-h1">Hello {user.name}</Header>
</Headers>
</Set>函式運算式不得包含空格
訊息範本函式運算式中不得有空格。例如：
允許：
{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}不允許：
{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}不支援巢狀函式
系統不支援在範本中呼叫另一個函式內的函式。舉例來說，您無法使用：
{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}以單引號括住範本函式中的字串常值
在函式中提供字串常值時，請以單引號而非雙引號括住。
例如：{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}避免在字串常值中使用特殊字元
避免在字串常值中使用特殊字元，例如「:」、「/」、「\」、「<」或「>」。這些字元可能會導致錯誤。如果字串常值需要特殊字元，請使用 Python 或 JavaScript 政策將值指派給變數，然後在範本中使用該變數。
在訊息範本中設定預設值
如果無法解析範本變數，Apigee 會代入空白字串。不過，您可以按照下列方式指定預設值：
<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>在上述範例中，如果無法解析變數 request.header.id，系統會將其值替換為 Unknown。例如：
Test message. id = Unknown
網址範本
URL 元素支援範本化，語法與其他元素相同。
這個範例顯示使用變數建構的網址：
<URL>{targeturl}</URL>本範例顯示通訊協定的預設值：
<URL>{protocol:https}://{site:google.com}/path</URL>JSON 酬載的舊版語法
在 Cloud 16.08.17 版之前的 Apigee 版本中，您無法使用大括號表示 JSON 酬載中的變數參照。在舊版中，您必須使用 variablePrefix 和 variableSuffix 屬性指定分隔符號字元，並使用這些字元包住變數名稱，如下所示：
<Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo","type":"@variable_name#"} </Payload> </Set>
雖然 Apigee 建議使用較新的大括號語法，但舊語法仍可運作。
使用訊息範本函式
Apigee 提供一組函式，您可以在訊息範本中使用這些函式，逸出、編碼、雜湊及格式化字串變數，如下所述。
範例：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."
}假設您想以自訂酬載將這則訊息傳回給用戶端呼叫端，一般來說，您會從目標回應酬載中擷取訊息，並使用 AssignMessage 將其新增至自訂 Proxy 回應 (也就是傳送回用戶端)。
以下是 ExtractVariables 政策，可將 user_message 資訊擷取至名為 standard.systemMessage 的變數：
<ExtractVariables name="EV-BackendErrorResponse"> <DisplayName>EV-BackendErrorResponse</DisplayName> <JSONPayload> <Variable name="standard.systemMessage"> <JSONPath>$.user_message</JSONPath> </Variable> </JSONPayload> </ExtractVariables>
現在，以下是完全有效的 AssignMessage 政策，可將擷取的變數新增至回應酬載 (Proxy 回應)：
<AssignMessage name="AM-SetStandardFaultResponse"> <DisplayName>AM-SetStandardFaultResponse</DisplayName> <Set> <Payload contentType="application/json"> { "systemMessage": "{standard.systemMessage}" } </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo>response</AssignTo> </AssignMessage>
很抱歉，發生問題。ExtractVariables 政策移除了訊息部分周圍的逸出引號字元。這表示傳回給用戶端的回應是無效的 JSON。這顯然不是您想要的結果！
{
"systemMessage": "Invalid value for "logonId" check your input."
}如要解決這個問題，您可以修改 AssignMessage 政策，使用訊息範本函式，在 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>response</AssignTo> </AssignMessage>
函式會逸出內嵌引號，產生有效的 JSON，這正是您想要的：
{
"systemMessage": "Invalid value for \"logonId\" check your input.",
}訊息範本是動態字串替代功能，可用於特定政策和 <TargetEndpoint> 定義。訊息範本函式可讓您在訊息範本中執行實用作業，例如雜湊、字串操作、字元逸出等。
舉例來說，在下列 AssignMessage 政策中，訊息範本會使用 toLowerCase() 函式：
<AssignMessage name="AM-Set-Custom-Response">
<AssignTo>response</AssignTo>
<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：雜湊函式會採用單一字串引數，並據此計算雜湊演算法。引數可以是字串常值 (以單引號括住) 或字串流程變數。
範例
函式呼叫：
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 編碼方式編碼字串。舉例來說，如果 value 包含 abc，則 encodeBase64(value) 會傳回字串 YWJj。 |
decodeBase64(string)
|
解碼 Base64 編碼的字串。舉例來說：當 value 包含 aGVsbG8sIHdvcmxk 時，decodeBase64(value) 會傳回字串 hello, world。valueaGVsbG8sIHdvcmxk |
引數
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>
大小寫轉換函式
將字串轉換為全大寫或全小寫字母。
語法
| 函式 | 說明 |
|---|---|
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 函式
傳回指定字串中，位於起始和結尾索引之間的字元。
語法
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：要進行替換的字串常值 (以單引號括住) 或字串流程變數。
- regex - 規則運算式。
- 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
|
取代 First 函式
只取代字串中第一個符合指定規則運算式的項目。
語法
replaceFirst(string,regex,value)
引數
string：要進行替換的字串常值 (以單引號括住) 或字串流程變數。regex：規則運算式。value：要用來取代字串中規則運算式相符項目的值。
字元逸出和編碼函式
函式會逸出或編碼字串中的特殊字元。
語法
| 函式 | 說明 |
|---|---|
escapeJSON(string)
|
反斜線逸出雙引號。 |
escapeXML(string)
|
將角括號、單引號、雙引號和連字號替換為對應的 XML 實體。適用於 XML 1.0 文件。 |
escapeXML11(string) |
作用方式與 escapeXML 相同，但適用於 XML 1.1 實體。請參閱下方的使用注意事項。 |
encodeHTML(string)
|
對單引號、角括號和 AND 符號進行編碼。 |
引數
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)
|
傳回以世界標準時間格式化的日期。 DEPRECATED：傳回以當地時區格式化的日期。 |
timeFormatMs(format,str)
|
傳回以世界標準時間格式化的日期。 DEPRECATED：傳回以當地時區格式化的日期。 |
timeFormatUTC(format,str)
|
傳回以世界標準時間格式化的日期。 |
timeFormatUTCMs(format,str)
|
傳回以世界標準時間格式化的日期。 |
引數
format：日期/時間格式字串。可以是字串常值 (以單引號括住) 或字串變數。如果格式包含半形冒號，請使用變數而非常值。請參閱本節的上一則附註。str：包含時間值的字串或字串流程變數。如果 timeFormatMs 為 true，則值可以是以秒為單位的 Epoch 時間，或以毫秒為單位的 Epoch 時間。
範例
假設有下列值，且當地時區為太平洋時區：
epoch_time_ms = 1494390266000epoch_time = 1494390266fmt1 = yyyy-MM-ddfmt2 = yyyy-MM-dd HH-mm-ssfmt3 = 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 第 4 版簽章的五個層級的串聯式 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 類別計算出的隨機長整數。
- 如果只有一個引數，系統會將其視為計算的最小值。
- 如有第二個引數，系統會將其視為計算的最大值。
範例
{randomLong()}結果如下所示：
5211338197474042880規則運算式文字產生器
產生符合指定規則運算式的文字字串。
語法
xeger(regex)
引數
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、node、number、boolean 或 string。預設值為 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：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(xpathexpression,xml,ns1)}範例 3：指定所需傳回類型
傳遞至 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
這項 jsonPath 查詢的回傳值會是包含單一元素的陣列。
根據預設，Apigee 中的 jsonPath 函式會假設您要使用單一值，以便在字串插補中使用。因此 Apigee 只會傳回陣列的第零個元素。如要要求完整陣列，請使用 true 做為第三個參數呼叫函式，如下一個範例所示。
範例 2
如果這是訊息範本：
{jsonPath('$.config.quota[?(@.operation=="ManageOrder")].appname',the_json_variable,true)}
而 the_json_variable 包含：
{
"config": {
"quota": [
{
"appname": "A",
"operation": "ManageOrder",
"value": "900"
},
{
"appname": "B",
"operation": "ManageOrder",
"value": "1000"
},
{
"appname": "B",
"operation": "SubmitOrder",
"value": "800"
}
]
}
}函式結果如下：
["A","B"]
在本例中，函式的第三個參數設為 true，因此 jsonPath 函式會以 JSON 陣列語法傳回完整陣列，而非第零個元素。
範例 3
如果 the_json_variable 包含：
{
"config": {
"quota": [
{
"appname": "A",
"operation": "ManageOrder",
"value": "900"
},
{
"appname": "B",
"operation": "ManageOrder",
"value": "1000"
},
{
"appname": "B",
"operation": "SubmitOrder",
"value": "800"
}
]
}
}而 the_query 包含：
$.config.quota[?(@.operation=="ManageOrder")].appname
訊息範本的結果：{jsonPath(the_query,the_json_variable,true)}
為 ["A","B"]
使用查詢變數，您就能在執行階段使用動態資料建構查詢。
您可以使用 AssignMessage 政策中的 <AssignVariable> 元素完成這項操作。
舉例來說，假設變數 operationname 包含值 ManageOrder，下列政策會將 the_query 設為上述查詢。
<AssignMessage>
<AssignVariable>
<Name>the_query</Name>
<Template>$.config.quota[?(@.operation=="{operationname}")].appname</Template>
</AssignVariable>
</AssignMessage>