JSONata 函数的表达式参考

本页是函数中可用的表达式语法、运算符和函数的完整参考。在为输出块、URL 字段、标头值、正文模板和运行条件编写表达式时使用它。

表达式分隔符

您在函数中定义的每个值要么是常量要么是表达式，而不是两者的混合。 MediaTailor 根据分隔符区分两者。

语法	Type	评测执行
`https://ads.example.com/vast`	常量	按原样返回，未进行评估。
`{%session.client_ip%}`	Expression	在运行时评估。结果取代了整个值。
`GET`	常量	按原样返回。
`{%'https://ads.example.com/vast?ip=' & session.client_ip%}`	Expression	在运行时评估。

重要

一个值要么完全是一个常量，要么完全是一个表达式。你不能将两者混合在一个值中。例如，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

字符串连接为 `&`

运&算符连接两个字符串值。 Non-string 值会自动转换为字符串。


'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()在进行数值比较或算术之前对其进行转换。将字符串与数字进行比较会产生意想不到的结果。

比较

运算符	描述	示例	结果
`=`	等于	`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`if 错误状态

布尔值

运算符	描述	示例
`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算符测试数组中是否存在一个值。


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

反省 (6)

函数	说明	示例	结果
`$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"]`
`$lookup(object, key)`	通过键名从对象中获取值	`$lookup(response.body, 'status')`	该`status`字段的值
`$each(object, func)`	将函数应用于对象的每个键值对	`$each({"a":1,"b":2}, function($v,$k){$k & '=' & $v})`	`["a=1", "b=2"]`

数字 (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`

字符串 (9)

函数	说明	示例	结果
`$uppercase(string)`	改为大写	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	改为小写	`$lowercase('Hello')`	`"hello"`
`$trim(string)`	移除 leading/trailing 空白	`$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)`	将字符串与正则表达式模式进行匹配	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	替换匹配的图案	`$replace('hello', 'l', 'r')`	`"herro"`
`$join(array, separator)`	将数组元素加入字符串	`$join(['a','b','c'], ',')`	`"a,b,c"`
`$split(string, separator)`	将字符串拆分成数组	`$split('a,b,c', ',')`	`["a", "b", "c"]`

数组 (7)

函数	说明	示例	结果
`$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]`
`$filter(array, func)`	返回函数返回 true 的元素	`$filter([1,2,3,4], function($v){$v > 2})`	`[3, 4]`
`$reduce(array, func, init)`	将数组缩减为单个值	`$reduce([1,2,3], function($prev,$val){$prev+$val}, 0)`	`6`

布尔值 (1)

函数	说明	示例	结果
`$not(value)`	不合逻辑	`$not(false)`	`true`

随机 (1)

函数	说明	示例	结果
`$random()`	介于 0（含）和 1（不包括）之间的随机数	`$random() > 0.5 ? 'A' : 'B'`	`"A"` 或 `"B"`

注意

$random()每次评估都会生成一个新值。如果您需要在多个输出键中使用相同的随机值，请先将其绑定到变量:($r := $random(); ...).

Date/time (4)

函数	说明	示例	结果
`$now()`	以 ISO 8601 字符串表示的当前时间戳	`$now()`	`"2024-01-15T12:00:00.000Z"`
`$millis()`	当前时间戳为自纪元以来的毫秒数	`$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-encoded	`$decodeUrl('hello%20world')` → `"hello world"`
`$decodeUrlComponent(string)`	解码组件 URL-encoded	`$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 构建

根据多个输入生成广告决策服务器网址。


{%'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'%}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

创建和管理

函数示例