翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Functions の JSONata 式リファレンス
<a name="monetization-functions-jsonata"></a>

このページは、 Functions で使用できる式の構文、演算子、関数の完全なリファレンスです。出力ブロック、URL フィールド、ヘッダー値、本文テンプレート、実行条件の式を記述するときに使用します。

## 式区切り文字
<a name="monetization-functions-jsonata-delimiters"></a>

関数で定義するすべての値は定数または式のいずれかであり、両方を組み合わせたものではありません。MediaTailor は、区切り文字に基づいて 2 つの を区別します。


| 構文 | タイプ | 評価 | 
| --- | --- | --- | 
| https://ads.example.com/vast | 定数 | 評価なしでそのまま返されます。 | 
| {%session.client\_ip%} | 式 | 実行時に評価されます。その結果、値全体が置き換えられます。 | 
| GET | 定数 | そのまま返されます。 | 
| {%'https://ads.example.com/vast?ip=' & session.client\_ip%} | 式 | 実行時に評価されます。 | 

**重要**  
値は、完全に定数または完全に式です。2 つの を 1 つの値に混在させることはできません。たとえば、`hello {%'world'%}` は無効です。静的テキストと動的値を組み合わせるには、式 内で文字列連結を使用します`{%'hello ' & 'world'%}`。

## 言語の基本
<a name="monetization-functions-jsonata-basics"></a>

### パスナビゲーションのドット表記
<a name="monetization-functions-jsonata-dot-notation"></a>

ドット表記を使用して入力データをトラバースします。各ドットは 1 つのレベルをオブジェクト階層に降順します。

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

### との文字列連結 `&`
<a name="monetization-functions-jsonata-concat"></a>

`&` 演算子は 2 つの文字列値を結合します。文字列以外の値は、自動的に文字列に変換されます。

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

条件に基づいて 2 つの値のいずれかを返すには、3 項演算子を使用します。

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

多方向分岐の 3 項式をネストできます。

```
$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) | 先頭/末尾の空白を削除する | $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 | $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(); ...)`。

### 日付/時刻 (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 エンコードされた文字列をデコードする | $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()`に を使用します。構造を保持しながら完全な URL をエンコードする必要がある`$encodeUrl()`場合にのみ使用します。

## 一般的なパターン
<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'%}
```

### 動的 URL 構造
<a name="monetization-functions-jsonata-patterns-url"></a>

複数の入力から広告決定サーバー URL を構築します。

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