Functions の JSONata 式リファレンス

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

式区切り文字

関数で定義するすべての値は定数または式のいずれかであり、両方を組み合わせたものではありません。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'%}。

言語の基本

パスナビゲーションのドット表記

ドット表記を使用して入力データをトラバースします。各ドットは 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

との文字列連結 `&`

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


'https://ads.example.com/vast?ip=' & session.client_ip
→ "https://ads.example.com/vast?ip=192.0.2.1"

'duration=' & 30
→ "duration=30"

条件 (三項) 式

条件に基づいて 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'

を使用した変数バインディング `:=`

式内に中間値を割り当てるには、括弧内の :=演算子を使用します。境界変数は括弧で囲まれた括弧に限定され、式の外部には保持されません。


(
  $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` エラーステータスの場合

ブール値

演算子	説明	例
`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)`	正規表現パターンと文字列を照合する	`$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()`	エポックからのミリ秒単位の現在のタイムスタンプ	`$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()にを使用します。構造を保持しながら完全な URL をエンコードする必要がある$encodeUrl()場合にのみ使用します。

一般的なパターン

フォールバック値

値が存在しない可能性がある場合は、デフォルトを指定します。


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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

の作成と管理

関数の例