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

Referensi ekspresi Jsonata untuk Fungsi

Halaman ini adalah referensi lengkap untuk sintaks ekspresi, operator, dan fungsi yang tersedia di Fungsi. Gunakan saat Anda menulis ekspresi untuk blok keluaran, bidang URL, nilai header, templat 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	Kembali apa adanya.
`{%'https://ads.example.com/vast?ip=' & session.client_ip%}`	Ekspresi	Dievaluasi saat runtime.

penting

Nilai adalah sama sekali konstan atau seluruhnya ekspresi. Anda tidak dapat mencampur keduanya dalam satu nilai. Misalnya, hello {%'world'%} tidak valid. Untuk menggabungkan teks statis dengan nilai dinamis, gunakan rangkaian 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

Rangkaian 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 (ternary)

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 ternary untuk percabangan multi-arah:


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

Pengikatan 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 kembali 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`
`%`	Modulo	`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 tidak 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 diutamakan:


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

catatan

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

Keanggotaan (`dalam`)

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 (`~ >`)

Operator rantai meneruskan hasil ekspresi tangan 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)`	Konversi ke string	`$string(200)`	`"200"`
`$number(value)`	Konversi ke angka	`$number('42')`	`42`
`$boolean(value)`	Konversi ke boolean	`$boolean(1)`	`true`

Introspeksi (4)

Fungsi	Deskripsi	Contoh	Hasil
`$length(string)`	Panjang tali	`$length('hello')`	`5`
`$count(array)`	Jumlah elemen array	`$count([1, 2, 3])`	`3`
`$exists(value)`	Periksa apakah nilai ada (tidak terdefinisi)	`$exists(temp.id)`	`true` atau `false`
`$keys(object)`	Dapatkan nama kunci objek	`$keys(response.body)`	`["id", "name"]`

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)`	Aritmatika berarti	`$average([10, 20, 30])`	`20`
`$abs(number)`	Nilai absolut	`$abs(-7)`	`7`
`$floor(number)`	Bulatkan ke bawah	`$floor(3.9)`	`3`
`$round(number, precision)`	Putaran ke presisi	`$round(3.456, 2)`	`3.46`

Tali (7)

Fungsi	Deskripsi	Contoh	Hasil
`$uppercase(string)`	Untuk huruf besar	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	Untuk huruf kecil	`$lowercase('Hello')`	`"hello"`
`$trim(string)`	Hapus leading/trailing spasi	`$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 pencocokan	`$replace('hello', 'l', 'r')`	`"herro"`

Array (5)

Fungsi	Deskripsi	Contoh	Hasil
`$append(arr1, arr2)`	Array gabungan	`$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)`	Menerapkan fungsi untuk setiap elemen	`$map([1,2,3], function($v){$v*2})`	`[2, 4, 6]`

Boolean (1)

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

Acak (1)

Fungsi	Deskripsi	Contoh	Hasil
`$random()`	Nomor 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 membutuhkan nilai acak yang sama di beberapa tombol 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)`	Mengkonversi ISO 8601 string ke milidetik	`$toMillis('2024-01-15T12:00:00.000Z')`	`1705320000000`
`$fromMillis(number)`	Mengkonversi milidetik ke ISO 8601 string	`$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 satu komponen (mengkodekan semua karakter khusus)	`$encodeUrlComponent('a&b=c')` → `"a%26b%3Dc"`
`$decodeUrl(string)`	Mendekode 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 mundur

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

Menjaga nilai output 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. Konversikan mereka sebelum perbandingan aritmatika atau numerik.


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

penting

Jika $number() menerima string non-numerik, ia kembali. undefined Gabungkan dengan $exists() ketika 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 ke 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

Menciptakan dan mengelola

Contoh fungsi

Referensi ekspresi Jsonata untuk Fungsi

Pembatas ekspresi

penting

Dasar-dasar bahasa

Notasi titik untuk navigasi jalur

Rangkaian string dengan &amp;

Ekspresi bersyarat (ternary)

Pengikatan variabel dengan: =

Operator

Aritmatika

penting

Perbandingan

Boolean

catatan

Keanggotaan (dalam)

Rantai (~ >)

Fungsi yang diizinkan

Jenis konversi (3)

Introspeksi (4)

Numerik (7)

Tali (7)

Array (5)

Boolean (1)

Acak (1)

catatan

Date/time (4)

Pengkodean (6)

Tip

Pola umum

Nilai mundur

Konstruksi URL dinamis

Pemeriksaan kode status untuk output HTTP_REQUEST

Konversi numerik dari parameter pemain

penting

Pemisahan lalu lintas acak

Klasifikasi jenis perangkat

Rangkaian string dengan `&`

Pengikatan variabel dengan`: =`

Keanggotaan (`dalam`)

Rantai (`~ >`)