Pembatas ekspresi Dasar-dasar bahasa Operator Fungsi yang diizinkan Pola umum

JSONata referensi ekspresi untuk Fungsi

Halaman ini adalah referensi lengkap untuk sintaks ekspresi, operator, dan fungsi yang tersedia di Functions. Gunakan saat Anda menulis ekspresi untuk blok keluaran, bidang URL, nilai header, template tubuh, dan kondisi jalankan.

Pembatas ekspresi

Setiap nilai yang Anda definisikan dalam suatu fungsi adalah konstanta atau ekspresi — bukan campuran keduanya. MediaTailor membedakan antara keduanya berdasarkan pembatas.

Sintaksis	Tipe	Evaluasi
`https://ads.example.com/vast`	Konstan	Dikembalikan apa adanya tanpa evaluasi.
`{%session.client_ip%}`	Ekspresi	Dievaluasi saat runtime. Hasilnya menggantikan seluruh nilai.
`GET`	Konstan	Dikembalikan apa adanya.
`{%'https://ads.example.com/vast?ip=' & session.client_ip%}`	Ekspresi	Dievaluasi saat runtime.

penting

Nilai adalah seluruhnya konstanta atau seluruhnya sebuah ekspresi. Anda tidak dapat mencampur keduanya dalam satu nilai. Misalnya, hello {%'world'%} tidak valid. Untuk menggabungkan teks statis dengan nilai dinamis, gunakan penggabungan string di dalam ekspresi:. {%'hello ' & 'world'%}

Dasar-dasar bahasa

Notasi titik untuk navigasi jalur

Gunakan notasi titik untuk melintasi data input. Setiap titik turun satu tingkat ke dalam hierarki objek.


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

Bidang yang hilang kembali null tanpa menimbulkan kesalahan:


temp.nonExistent               → null
temp.nonExistent.deeply.nested → null

Gabungan string dengan `&`

&Operator menggabungkan dua nilai string. Non-string nilai dikonversi ke string secara otomatis.


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

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

Ekspresi bersyarat (terner)

Gunakan operator ternary untuk mengembalikan salah satu dari dua nilai berdasarkan suatu kondisi.


condition ? value_if_true : value_if_false

Contoh:


$exists(player_params.env) ? player_params.env : 'prod'
response.statusCode = 200 ? response.body.id : 'unknown'
$random() > 0.5 ? 'groupA' : 'groupB'

Anda dapat membuat sarang ekspresi terner untuk percabangan multi-arah:


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

Mengikat variabel dengan`: =`

Gunakan := operator di dalam tanda kurung untuk menetapkan nilai perantara dalam ekspresi. Variabel terikat dicakup ke tanda kurung terlampir dan tidak bertahan di luar ekspresi.


(
  $base := 'https://ads.example.com';
  $base & '/vast?ip=' & session.client_ip
)

Titik koma memisahkan pernyataan di dalam tanda kurung. Pernyataan terakhir adalah nilai pengembalian dari ekspresi.


(
  $code := response.statusCode;
  $code != null and $code >= 200 and $code < 300
    ? response.body.value
    : 'fallback'
)

Operator

Aritmatika

Operator	Deskripsi	Contoh	Hasil
`+`	Penambahan	`5 + 3`	`8`
`-`	Pengurangan	`10 - 4`	`6`
`*`	Perkalian	`6 * 7`	`42`
`/`	Pembagian	`15 / 4`	`3.75`
`%`	Module	`17 % 5`	`2`

penting

Nilai input dari parameter pemain dan data sesi tiba sebagai string. Gunakan $number() untuk mengonversinya sebelum perbandingan numerik atau aritmatika. Membandingkan string dengan angka menghasilkan hasil yang tidak terduga.

Perbandingan

Operator	Deskripsi	Contoh	Hasil
`=`	Sama dengan	`response.statusCode = 200`	`true`
`!=`	Tidak sama dengan	`player_params.region != 'us-east-1'`	`true`jika bukan us-east-1
`<`	Kurang dari	`avail.index < 3`	`true`jika di bawah 3
`>`	Lebih besar dari	`$number(player_params.age) > 18`	`true`jika lebih dari 18
`<=`	Kurang dari atau sama	`$count(items) <= 10`	`true`jika 10 atau kurang
`>=`	Lebih besar dari atau sama	`response.statusCode >= 400`	`true`jika status kesalahan

Boolean

Operator	Deskripsi	Contoh
`and`	Logis DAN	`response.statusCode = 200 and $exists(response.body.id)`
`or`	Logis ATAU	`player_params.region = 'us-east-1' or player_params.region = 'us-west-2'`

Gunakan tanda kurung untuk prioritas:


score > 0.5 and (tier = 'premium' or tier = 'gold')

catatan

Gunakan $not() untuk negasi logis. Tidak ada operator not kata kunci.

Keanggotaan (`in`)

inOperator menguji apakah nilai ada dalam array.


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

Rantai-rantai (`~ >`)

Operator rantai meneruskan hasil ekspresi kiri sebagai argumen pertama ke fungsi di sebelah kanan.


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

Fungsi yang diizinkan

MediaTailor mendukung fungsi bawaan berikut. Fungsi apa pun yang tidak tercantum di sini diblokir dan menyebabkan kesalahan validasi saat Anda membuat atau memperbarui fungsi.

Jenis konversi (3)

Fungsi	Deskripsi	Contoh	Hasil
`$string(value)`	Ubah ke string	`$string(200)`	`"200"`
`$number(value)`	Ubah menjadi angka	`$number('42')`	`42`
`$boolean(value)`	Konversi ke boolean	`$boolean(1)`	`true`

Introspeksi (6)

Fungsi	Deskripsi	Contoh	Hasil
`$length(string)`	Panjang string	`$length('hello')`	`5`
`$count(array)`	Jumlah elemen array	`$count([1, 2, 3])`	`3`
`$exists(value)`	Periksa apakah nilai ada (tidak ditentukan)	`$exists(temp.id)`	`true` atau `false`
`$keys(object)`	Dapatkan nama kunci objek	`$keys(response.body)`	`["id", "name"]`
`$lookup(object, key)`	Dapatkan nilai dari objek dengan nama kunci	`$lookup(response.body, 'status')`	Nilai `status` bidang
`$each(object, func)`	Terapkan fungsi ke setiap pasangan kunci-nilai suatu objek	`$each({"a":1,"b":2}, function($v,$k){$k & '=' & $v})`	`["a=1", "b=2"]`

Numerik (7)

Fungsi	Deskripsi	Contoh	Hasil
`$sum(array)`	Jumlah array	`$sum([1, 2, 3])`	`6`
`$max(array)`	Nilai maksimum	`$max([10, 5, 20])`	`20`
`$min(array)`	Nilai minimum	`$min([10, 5, 20])`	`5`
`$average(array)`	Rata-rata aritmatika	`$average([10, 20, 30])`	`20`
`$abs(number)`	Nilai absolut	`$abs(-7)`	`7`
`$floor(number)`	Bulatkan ke bawah	`$floor(3.9)`	`3`
`$round(number, precision)`	Bulat ke presisi	`$round(3.456, 2)`	`3.46`

Tali (9)

Fungsi	Deskripsi	Contoh	Hasil
`$uppercase(string)`	Ke huruf besar	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	Untuk huruf kecil	`$lowercase('Hello')`	`"hello"`
`$trim(string)`	Hapus sp leading/trailing asi	`$trim(' hi ')`	`"hi"`
`$substring(string, start, length)`	Ekstrak substring (berbasis nol)	`$substring('abcdef', 2, 3)`	`"cde"`
`$contains(string, pattern)`	Periksa apakah string berisi pola	`$contains(session.user_agent, 'CTV')`	`true` atau `false`
`$match(string, pattern)`	Cocokkan string dengan pola regex	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	Ganti pola yang cocok	`$replace('hello', 'l', 'r')`	`"herro"`
`$join(array, separator)`	Gabungkan elemen array ke dalam string	`$join(['a','b','c'], ',')`	`"a,b,c"`
`$split(string, separator)`	Pisahkan string menjadi array	`$split('a,b,c', ',')`	`["a", "b", "c"]`

Array (7)

Fungsi	Deskripsi	Contoh	Hasil
`$append(arr1, arr2)`	Gabungkan array	`$append([1, 2], [3, 4])`	`[1, 2, 3, 4]`
`$reverse(array)`	Urutan terbalik	`$reverse([1, 2, 3])`	`[3, 2, 1]`
`$sort(array)`	Urutkan array	`$sort([3, 1, 2])`	`[1, 2, 3]`
`$distinct(array)`	Hapus duplikat	`$distinct([1, 2, 2, 3])`	`[1, 2, 3]`
`$map(array, func)`	Terapkan fungsi untuk setiap elemen	`$map([1,2,3], function($v){$v*2})`	`[2, 4, 6]`
`$filter(array, func)`	Mengembalikan elemen di mana fungsi mengembalikan true	`$filter([1,2,3,4], function($v){$v > 2})`	`[3, 4]`
`$reduce(array, func, init)`	Kurangi array menjadi satu nilai	`$reduce([1,2,3], function($prev,$val){$prev+$val}, 0)`	`6`

Boolean (1)

Fungsi	Deskripsi	Contoh	Hasil
`$not(value)`	Logis TIDAK	`$not(false)`	`true`

Acak (1)

Fungsi	Deskripsi	Contoh	Hasil
`$random()`	Angka acak antara 0 (inklusif) dan 1 (eksklusif)	`$random() > 0.5 ? 'A' : 'B'`	`"A"` atau `"B"`

catatan

$random()menghasilkan nilai baru pada setiap evaluasi. Jika Anda memerlukan nilai acak yang sama di beberapa kunci keluaran, ikat ke variabel terlebih dahulu:($r := $random(); ...).

Date/time (4)

Fungsi	Deskripsi	Contoh	Hasil
`$now()`	Stempel waktu saat ini sebagai string ISO 8601	`$now()`	`"2024-01-15T12:00:00.000Z"`
`$millis()`	Stempel waktu saat ini sebagai milidetik sejak zaman	`$millis()`	`1705320000000`
`$toMillis(string)`	Ubah string ISO 8601 menjadi milidetik	`$toMillis('2024-01-15T12:00:00.000Z')`	`1705320000000`
`$fromMillis(number)`	Ubah milidetik ke string ISO 8601	`$fromMillis(1705320000000)`	`"2024-01-15T12:00:00.000Z"`

Pengkodean (6)

Fungsi	Deskripsi	Contoh
`$encodeUrl(string)`	URL encode (mempertahankan karakter struktural seperti`/`,`?`,`&`)	`$encodeUrl('https://example.com/path?q=hello world')`
`$encodeUrlComponent(string)`	URL menyandikan komponen tunggal (mengkodekan semua karakter khusus)	`$encodeUrlComponent('a&b=c')` → `"a%26b%3Dc"`
`$decodeUrl(string)`	Dekode string URL-encoded	`$decodeUrl('hello%20world')` → `"hello world"`
`$decodeUrlComponent(string)`	Mendekode komponen URL-encoded	`$decodeUrlComponent('a%26b')` → `"a&b"`
`$base64encode(string)`	Encode ke Base64	`$base64encode('hello')` → `"aGVsbG8="`
`$base64decode(string)`	Dekode dari Base64	`$base64decode('aGVsbG8=')` → `"hello"`

Tip

Gunakan $encodeUrlComponent() untuk nilai parameter kueri individu. Gunakan $encodeUrl() hanya ketika Anda perlu menyandikan URL lengkap sambil mempertahankan strukturnya.

Pola umum

Nilai fallback

Berikan default ketika nilai mungkin tidak ada.


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

Konstruksi URL dinamis

Buat URL server keputusan iklan dari beberapa input.


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

Pemeriksaan kode status untuk output HTTP_REQUEST

Lindungi nilai keluaran terhadap kegagalan HTTP.


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

Konversi numerik dari parameter pemain

Parameter pemain tiba sebagai string. Ubah mereka sebelum perbandingan aritmatika atau numerik.


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

penting

Jika $number() menerima string non-numerik, ia kembaliundefined. Gabungkan dengan $exists() kapan parameter mungkin hilang atau tidak valid:($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short').

Pemisahan lalu lintas acak

Tetapkan pemirsa untuk grup eksperimen menggunakan$random().


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

Klasifikasi jenis perangkat

Klasifikasi perangkat berdasarkan string agen pengguna.


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

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Membuat dan mengelola

Contoh fungsi

JSONata referensi ekspresi untuk Fungsi

Pembatas ekspresi

penting

Dasar-dasar bahasa

Notasi titik untuk navigasi jalur

Gabungan string dengan &amp;

Ekspresi bersyarat (terner)

Mengikat variabel dengan: =

Operator

Aritmatika

penting

Perbandingan

Boolean

catatan

Keanggotaan (in)

Rantai-rantai (~ >)

Fungsi yang diizinkan

Jenis konversi (3)

Introspeksi (6)

Numerik (7)

Tali (9)

Array (7)

Boolean (1)

Acak (1)

catatan

Date/time (4)

Pengkodean (6)

Tip

Pola umum

Nilai fallback

Konstruksi URL dinamis

Pemeriksaan kode status untuk output HTTP_REQUEST

Konversi numerik dari parameter pemain

penting

Pemisahan lalu lintas acak

Klasifikasi jenis perangkat

Gabungan string dengan `&`

Mengikat variabel dengan`: =`

Keanggotaan (`in`)

Rantai-rantai (`~ >`)