本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 函数的 jsonata 表达式参考
<a name="monetization-functions-jsonata"></a>

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

## 表达式分隔符
<a name="monetization-functions-jsonata-delimiters"></a>

你在函数中定义的每个值要么是一个常量，要么是一个表达式，而不是两者的混合。 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'%}` 

## 语言基础知识
<a name="monetization-functions-jsonata-basics"></a>

### 用于路径导航的点符号
<a name="monetization-functions-jsonata-dot-notation"></a>

使用点符号遍历输入数据。每个点向下移动一级，进入对象层次结构。

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

### 字符串连接为 `&amp;`
<a name="monetization-functions-jsonata-concat"></a>

运`&`算符连接两个字符串值。 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"
```

### 条件（三元）表达式
<a name="monetization-functions-jsonata-ternary"></a>

使用三元运算符根据条件返回两个值中的一个。

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

### 变量绑定为`:=`
<a name="monetization-functions-jsonata-binding"></a>

使用括号内的`:=`运算符在表达式中分配中间值。绑定变量的作用域限制在括号内，并且不会在表达式之外保留。

```
(
  $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'
)
```

## 运算符
<a name="monetization-functions-jsonata-operators"></a>

### 算术
<a name="monetization-functions-jsonata-operators-arithmetic"></a>


| 运算符 | 描述 | 示例 | 结果 | 
| --- | --- | --- | --- | 
| \+ | 加 | 5 \+ 3 | 8 | 
| - | 减 | 10 - 4 | 6 | 
| \* | 乘 | 6 \* 7 | 42 | 
| / | 除 | 15 / 4 | 3.75 | 
| % | 取模 | 17 % 5 | 2 | 

**重要**  
来自玩家参数和会话数据的输入值以字符串形式到达。`$number()`用于在数值比较或算术之前对其进行转换。将字符串与数字进行比较会产生意想不到的结果。

### 比较
<a name="monetization-functions-jsonata-operators-comparison"></a>


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

### 布尔值
<a name="monetization-functions-jsonata-operators-boolean"></a>


| 运算符 | 描述 | 示例 | 
| --- | --- | --- | 
| 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`)
<a name="monetization-functions-jsonata-operators-membership"></a>

该`in`运算符测试数组中是否存在一个值。

```
'premium' in segments     → true if segments contains 'premium'
player_params.region in ['us-east-1', 'us-west-2']  → true
```

### 链接 (`~ >`)
<a name="monetization-functions-jsonata-operators-chaining"></a>

链接运算符将左侧表达式的结果作为第一个参数传递给右边的函数。

```
session.user_agent ~> $lowercase ~> $trim
→ equivalent to $trim($lowercase(session.user_agent))
```

## 允许的函数
<a name="monetization-functions-jsonata-allowed"></a>

MediaTailor 支持以下内置函数。此处未列出的任何函数都会被阻止，并且在您创建或更新函数时会导致验证错误。

### 类型转换 (3)
<a name="monetization-functions-jsonata-allowed-type"></a>


| 函数 | 说明 | 示例 | 结果 | 
| --- | --- | --- | --- | 
| $string(value) | 转换为字符串 | $string(200) | "200" | 
| $number(value) | 转换为数字 | $number('42') | 42 | 
| $boolean(value) | 转换为布尔值 | $boolean(1) | true | 

### 内省 (4)
<a name="monetization-functions-jsonata-allowed-introspection"></a>


| 函数 | 说明 | 示例 | 结果 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-numeric"></a>


| 函数 | 说明 | 示例 | 结果 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-string"></a>


| 函数 | 说明 | 示例 | 结果 | 
| --- | --- | --- | --- | 
| $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" | 

### 数组 (5)
<a name="monetization-functions-jsonata-allowed-array"></a>


| 函数 | 说明 | 示例 | 结果 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-boolean"></a>


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

### 随机 (1)
<a name="monetization-functions-jsonata-allowed-random"></a>


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

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

### Date/time (4)
<a name="monetization-functions-jsonata-allowed-datetime"></a>


| 函数 | 说明 | 示例 | 结果 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-encoding"></a>


| 函数 | 说明 | 示例 | 
| --- | --- | --- | 
| $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 进行编码同时保留其结构时才使用。

## 常见模式
<a name="monetization-functions-jsonata-patterns"></a>

### 备用值
<a name="monetization-functions-jsonata-patterns-fallback"></a>

当值可能不存在时，请提供默认值。

```
{%$exists(player_params.region) ? player_params.region : 'us-east-1'%}
```

### 动态网址构造
<a name="monetization-functions-jsonata-patterns-url"></a>

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

```
{%'https://ads.example.com/v1/vast?ip=' & $encodeUrlComponent(session.client_ip) & '&ua=' & $encodeUrlComponent(session.user_agent) & '&sid=' & session.id%}
```

### 状态码检查 HTTP\_REQUEST 输出
<a name="monetization-functions-jsonata-patterns-status"></a>

保护输出值免受 HTTP 故障的影响。

```
{%response.statusCode != null and response.statusCode = 200 ? response.body.envelope : 'default-envelope'%}
```

### 根据玩家参数进行数值转换
<a name="monetization-functions-jsonata-patterns-numeric"></a>

玩家参数以字符串形式到达。在算术或数字比较之前对其进行转换。

```
{%$number(player_params.max_duration) > 30 ? 'long' : 'short'%}
```

**重要**  
如果`$number()`收到非数字字符串，则返回`undefined`。将其与`$exists()`参数可能缺失或无效的时间结合起来:`($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short')`.

### 随机流量分割
<a name="monetization-functions-jsonata-patterns-random"></a>

使用将观众分配到实验组`$random()`。

```
{%$random() > 0.5 ? 'https://ads.example.com/v1/vast-a' : 'https://ads.example.com/v1/vast-b'%}
```

### 设备类型分类
<a name="monetization-functions-jsonata-patterns-device"></a>

根据用户代理字符串对设备进行分类。

```
{%$contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop'%}
```