本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
函數的 JSONata 表達式參考
此頁面是 Functions 中可用表達式語法、運算子和函數的完整參考。當您為輸出區塊、URL 欄位、標頭值、內文範本和執行條件撰寫表達式時，請使用它。
運算式分隔符號
您在函數中定義的每個值都是常數或表達式，而不是兩者的混合。MediaTailor 會根據分隔符號區分兩者。
| 語法 | Type | 評估 |
|---|---|---|
https://ads.example.com/vast |
常數 | 依原樣傳回，沒有評估。 |
{%session.client_ip%} |
表達式 | 在執行時間評估。結果會取代整個值。 |
GET |
常數 | 依原狀傳回。 |
{%'https://ads.example.com/vast?ip=' &
session.client_ip%} |
表達式 | 在執行時間評估。 |
重要
值完全是常數或完全是表達式。您不能將兩者混合為單一值。例如，hello {%'world'%} 是無效的。若要將靜態文字與動態值結合，請在表達式內使用字串串連：{%'hello ' & 'world'%}。
語言基本概念
路徑導覽的點表示法
使用點表示法來周遊輸入資料。每個點會將一個層級遞減到物件階層中。
session.client_ip → the viewer's IP address response.body.envelope → a field inside a parsed JSON response player_params.campaign_id → a player parameter
傳回缺少的欄位null而不引發錯誤：
temp.nonExistent → null temp.nonExistent.deeply.nested → null
與 的字串串連 &
& 運算子會聯結兩個字串值。非字串值會自動轉換為字串。
'https://ads.example.com/vast?ip=' & session.client_ip → "https://ads.example.com/vast?ip=192.0.2.1" 'duration=' & 30 → "duration=30"
條件式 （三元） 表達式
使用三元運算子根據條件傳回兩個值的其中之一。
condition ? value_if_true : value_if_false
範例：
$exists(player_params.env) ? player_params.env : 'prod' response.statusCode = 200 ? response.body.id : 'unknown' $random() > 0.5 ? 'groupA' : 'groupB'
您可以巢狀多向分支的三元表達式：
$contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop'
使用 的變數繫結 :=
使用括號內的:=運算子在表達式中指派中繼值。邊界變數的範圍是括住的括號，不會保留在表達式之外。
( $base := 'https://ads.example.com'; $base & '/vast?ip=' & session.client_ip )
分號會在括號內分隔陳述式。最後一個陳述式是表達式的傳回值。
( $code := response.statusCode; $code != null and $code >= 200 and $code < 300 ? response.body.value : 'fallback' )
運算子
算術
| 運算子 | 說明 | 範例 | 結果 |
|---|---|---|---|
+ | 加法 | 5 + 3 | 8 |
- | 減法 | 10 - 4 | 6 |
* | 乘法 | 6 * 7 | 42 |
/ | 除法 | 15 / 4 | 3.75 |
% | 模數 | 17 % 5 | 2 |
重要
來自玩家參數和工作階段資料的輸入值會以字串的形式抵達。使用 $number() 在數值比較或算術之前進行轉換。比較字串與數字會產生非預期的結果。
Comparison (比較)
| 運算子 | 說明 | 範例 | 結果 |
|---|---|---|---|
= | 等於 | response.statusCode = 200 | true |
!= | 不等於 | player_params.region != 'us-east-1' | true 如果不是 us-east-1 |
< | Less than | avail.index < 3 | true 如果低於 3 |
> | Greater than | $number(player_params.age) > 18 | true 如果超過 18 |
<= | Less than or equal | $count(items) <= 10 | true 如果 10 個或更少 |
>= | Greater than or equal | response.statusCode >= 400 | true 如果錯誤狀態 |
Boolean
| 運算子 | 說明 | 範例 |
|---|---|---|
and | 邏輯 AND | response.statusCode = 200 and $exists(response.body.id) |
or | 邏輯 OR | player_params.region = 'us-east-1' or player_params.region = 'us-west-2' |
使用括號做為優先順序：
score > 0.5 and (tier = 'premium' or tier = 'gold')
注意
使用 $not()進行邏輯否定。沒有not關鍵字運算子。
成員資格 (in)
in 運算子會測試陣列中是否存在值。
'premium' in segments → true if segments contains 'premium' player_params.region in ['us-east-1', 'us-west-2'] → true
鏈結 (~>)
鏈結運算子會將左側表達式的結果做為第一個引數傳遞至右側的函數。
session.user_agent ~> $lowercase ~> $trim → equivalent to $trim($lowercase(session.user_agent))
允許的函數
MediaTailor 支援下列內建函數。此處未列出的任何函數都會遭到封鎖，並在您建立或更新函數時造成驗證錯誤。
類型轉換 (3)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$string(value) | 轉換為字串 | $string(200) | "200" |
$number(value) | 轉換為數字 | $number('42') | 42 |
$boolean(value) | 轉換為布林值 | $boolean(1) | true |
自我檢查 (4)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$length(string) | 字串長度 | $length('hello') | 5 |
$count(array) | 陣列元素計數 | $count([1, 2, 3]) | 3 |
$exists(value) | 檢查值是否存在 （非未定義） | $exists(temp.id) | true 或 false |
$keys(object) | 取得物件金鑰名稱 | $keys(response.body) | ["id", "name"] |
數值 (7)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$sum(array) | 陣列的總和 | $sum([1, 2, 3]) | 6 |
$max(array) | 最大值 | $max([10, 5, 20]) | 20 |
$min(array) | 最小值 | $min([10, 5, 20]) | 5 |
$average(array) | 算術平均值 | $average([10, 20, 30]) | 20 |
$abs(number) | 絕對值 | $abs(-7) | 7 |
$floor(number) | 四捨五入 | $floor(3.9) | 3 |
$round(number, precision) | 四捨五入到精確度 | $round(3.456, 2) | 3.46 |
字串 (7)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$uppercase(string) | 至大寫 | $uppercase('hello') | "HELLO" |
$lowercase(string) | 小寫 | $lowercase('Hello') | "hello" |
$trim(string) | 移除前導/追蹤空格 | $trim(' hi ') | "hi" |
$substring(string, start, length) | 擷取子字串 （以零為基礎） | $substring('abcdef', 2, 3) | "cde" |
$contains(string, pattern) | 檢查字串是否包含模式 | $contains(session.user_agent, 'CTV') | true 或 false |
$match(string, pattern) | 比對字串與 regex 模式 | $match('abc-123', /[0-9]+/) | {"match": "123", ...} |
$replace(string, pattern, replacement) | 取代相符模式 | $replace('hello', 'l', 'r') | "herro" |
陣列 (5)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$append(arr1, arr2) | 串連陣列 | $append([1, 2], [3, 4]) | [1, 2, 3, 4] |
$reverse(array) | 反向順序 | $reverse([1, 2, 3]) | [3, 2, 1] |
$sort(array) | 排序陣列 | $sort([3, 1, 2]) | [1, 2, 3] |
$distinct(array) | 移除重複項目 | $distinct([1, 2, 2, 3]) | [1, 2, 3] |
$map(array, func) | 將函數套用至每個元素 | $map([1,2,3], function($v){$v*2}) | [2, 4, 6] |
布林值 (1)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$not(value) | 邏輯 NOT | $not(false) | true |
隨機 (1)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$random() | 介於 0 （含） 和 1 （不含） 之間的隨機數 | $random() > 0.5 ? 'A' : 'B' | "A" 或 "B" |
注意
$random() 每次評估都會產生新的值。如果您在多個輸出索引鍵中需要相同的隨機值，請先將其繫結至變數：($r := $random(); ...)。
日期/時間 (4)
| 函式 | 說明 | 範例 | 結果 |
|---|---|---|---|
$now() | ISO 8601 字串目前的時間戳記 | $now() | "2024-01-15T12:00:00.000Z" |
$millis() | 自 epoch 以來以毫秒為單位的目前時間戳記 | $millis() | 1705320000000 |
$toMillis(string) | 將 ISO 8601 字串轉換為毫秒 | $toMillis('2024-01-15T12:00:00.000Z') | 1705320000000 |
$fromMillis(number) | 將毫秒轉換為 ISO 8601 字串 | $fromMillis(1705320000000) | "2024-01-15T12:00:00.000Z" |
編碼 (6)
| 函式 | 說明 | 範例 |
|---|---|---|
$encodeUrl(string) | URL 編碼 （保留結構字元，例如 /、?、&) | $encodeUrl('https://example.com/path?q=hello world') |
$encodeUrlComponent(string) | URL 編碼單一元件 （編碼所有特殊字元） | $encodeUrlComponent('a&b=c') → "a%26b%3Dc" |
$decodeUrl(string) | 解碼 URL 編碼字串 | $decodeUrl('hello%20world') → "hello world" |
$decodeUrlComponent(string) | 解碼 URL 編碼元件 | $decodeUrlComponent('a%26b') → "a&b" |
$base64encode(string) | 編碼至 Base64 | $base64encode('hello') → "aGVsbG8=" |
$base64decode(string) | 從 Base64 解碼 | $base64decode('aGVsbG8=') → "hello" |
提示
將 $encodeUrlComponent()用於個別查詢參數值。$encodeUrl() 只有在您需要編碼完整 URL，同時保留其結構時使用 。
常見模式
備用值
在值可能不存在時提供預設值。
{%$exists(player_params.region) ? player_params.region : 'us-east-1'%}
動態 URL 建構
從多個輸入建置廣告決策伺服器 URL。
{%'https://ads.example.com/v1/vast?ip=' & $encodeUrlComponent(session.client_ip) & '&ua=' & $encodeUrlComponent(session.user_agent) & '&sid=' & session.id%}
HTTP_REQUEST 輸出的狀態碼檢查
防止輸出值發生 HTTP 失敗。
{%response.statusCode != null and response.statusCode = 200 ? response.body.envelope : 'default-envelope'%}
從玩家參數的數值轉換
玩家參數會以字串的形式抵達。在算術或數值比較之前轉換它們。
{%$number(player_params.max_duration) > 30 ? 'long' : 'short'%}
重要
如果 $number()收到非數字字串，則會傳回 undefined。當 參數可能遺失或無效$exists()時，將其與 合併：($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short')。
隨機流量分割
使用 將檢視器指派給實驗群組$random()。
{%$random() > 0.5 ? 'https://ads.example.com/v1/vast-a' : 'https://ads.example.com/v1/vast-b'%}
裝置類型分類
根據使用者代理程式字串分類裝置。
{%$contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop'%}
