Filter

REST API Ad Manager mendukung pemfilteran pada metode List. Sintaksis string filter secara resmi ditentukan dalam tata bahasa EBNF.

Untuk memulai, berikut ini beberapa contoh kasus penggunaan umum.

Contoh	Arti
orders.updateTime > "2024-01-01T00:00:00-5:00"	Mencantumkan pesanan dengan updateTime setelah 1 Januari 2024 di Zona Waktu Standar Timur
lineItems.targeting.geoTargeting.targetedGeoIds:2840	Mencantumkan item baris dengan penargetan geografis yang berisi Amerika Serikat (ID target geografis 2480)
lineItems.displayName = "*_interstitial"	Mencantumkan item baris yang memiliki nama tampilan yang diakhiri dengan string _interstitial
orders.displayName = "*video*"	Mencantumkan pesanan yang memiliki nama tampilan yang berisi string video
displayName:"video"	Mencantumkan pesanan yang memiliki nama tampilan yang berisi string video (sintaksis alternatif)

Tips: Filter harus dienkode ke URL untuk permintaan GET. Misalnya:
String filter: orders.updateTime > "2024-01-01T00:00:00-5:00"
Dienkode URL: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22.
Hal ini ditangani secara otomatis oleh library klien.

Literal

Nilai literal sederhana (contoh: 42, Hugo) adalah nilai yang akan dicocokkan. Literal yang muncul sendiri akan dicocokkan secara fuzzy dengan semua kolom yang didukung pada resource. Resource mendokumentasikan kolom mana yang dipertimbangkan untuk pencocokan pada metode list. Fitur ini sebanding dengan penelusuran universal di UI Ad Manager, tetapi memiliki cakupan satu jenis resource.

Literal string yang berisi spasi harus digabungkan dengan tanda kutip ganda (contoh: "Foo bar"). Tanda kutip tunggal tidak dapat digunakan untuk menggabungkan literal string.

Operator logika

REST API Ad Manager mendukung operator biner AND dan OR.

Perhatian: Operator ini peka huruf besar/kecil. Literal and dan or diperlakukan sebagai Literal.

Operator	Contoh	Arti
AND	a AND b	Benar jika a dan b benar.
OR	a OR b OR c	Benar jika salah satu dari a, b, c benar.

Catatan: Untuk mencocokkan pola ucapan yang umum, operator OR memiliki prioritas lebih tinggi daripada AND, tidak seperti yang ditemukan dalam sebagian besar bahasa pemrograman. Ekspresi a AND b OR c dievaluasi sebagai a AND (b OR c). Jika memungkinkan, gunakan tanda kurung eksplisit untuk menghindari kebingungan.

Operator negasi

Ad Manager REST API menyediakan operator unary NOT dan -. Ini dapat digunakan secara bergantian.

Operator	Contoh	Arti
NOT	NOT a	Benar jika a tidak benar.
-	-a	Benar jika a tidak benar.

Operator perbandingan

Ad Manager REST API mendukung operator perbandingan biner =, !=, <, >, <=, dan >= untuk kolom string, numerik, stempel waktu, dan durasi.

Operator	Contoh	Arti
=	a = true	Benar jika a benar.
!=	a != 42	Benar kecuali jika a sama dengan 42.
<	a < 42	Benar jika a adalah nilai numerik kurang dari 42.
>	a > "foo"	Benar jika a diurutkan secara leksik setelah "foo".
<=	a <= "foo"	Benar jika a adalah "foo" atau secara leksik sebelumnya.
>=	a >= 42	Benar jika a adalah nilai numerik 42 atau lebih tinggi.

Catatan: Tidak seperti kebanyakan bahasa pemrograman, nama kolom harus muncul di sisi kiri operator perbandingan; sisi kanan hanya menerima operator literal dan logika.

Karena filter diterima sebagai string kueri, konversi jenis terjadi untuk menerjemahkan string ke nilai berjenis kuat yang sesuai:

• String mengharapkan tanda kutip ganda. Contoh: "Foo bar".
• Enum mengharapkan representasi string enum (peka huruf besar/kecil).
• Boolean mengharapkan nilai literal true dan false.
• Bilangan mengharapkan representasi bilangan bulat atau float standar. Untuk float, eksponen didukung. Contoh: 2.997e9.
• Durasi mengharapkan representasi numerik yang diikuti dengan akhiran s (untuk detik). Contoh: "20s", "1.2s".
• Stempel waktu mengharapkan string berformat RFC-3339. Contoh: "2012-04-21T11:30:00-04:00". Offset UTC didukung.

Perhatian: ID true, false, dan null hanya membawa makna intrinsik saat digunakan dalam konteks referensi kolom yang diketik.

Karakter pengganti

Saat membandingkan string untuk kesetaraan, Ad Manager REST API mendukung karakter pengganti menggunakan karakter *.

Contoh	Arti
a = "*.foo"	Benar jika a diakhiri dengan ".foo".

Operator traversal

Ad Manager REST API mendukung operator ., yang menunjukkan traversal melalui pesan, peta, atau struct.

Contoh	Arti
a.b = true	Benar jika a memiliki kolom b boolean yang benar.
a.b > 42	Benar jika a memiliki kolom b numerik yang lebih besar dari 42.
a.b.c = "foo"	Benar jika a.b memiliki kolom c string yang berupa "foo".

Traversal ditulis menggunakan nama kolom dari resource. Masing-masing layanan dapat menentukan subset kolom yang didukung untuk traversal.

Penting: Operator . tidak dapat digunakan untuk melintasi kolom atau daftar berulang, kecuali untuk penggunaan khusus dengan operator :.

Memiliki operator

REST API Ad Manager mendukung operator :, yang berarti "has". Class ini dapat digunakan dengan koleksi (kolom atau peta berulang), pesan, dan String, serta berperilaku sedikit berbeda dalam setiap kasus.

Kueri kolom string untuk melihat apakah string berisi substring yang cocok:

Contoh	Arti
r.displayName:"_250x250"	Benar jika kolom String r.displayName berisi substring _250x250.

Kueri kolom berulang untuk melihat apakah struktur berulang berisi elemen yang cocok:

Contoh	Arti
r:42	Benar jika r berisi 42.
r.foo:42	Benar jika r berisi elemen e yang sedemikian rupa sehingga e.foo = 42.

Penting: Filter tidak dapat mengkueri elemen tertentu pada kolom berulang untuk sebuah nilai. Misalnya, e.0.foo = 42 dan e[0].foo = 42 bukan filter yang valid.

Peta, struct, dan pesan dapat membuat kueri untuk mengetahui keberadaan kolom dalam peta atau nilai tertentu:

Contoh	Arti
m:foo	Benar jika m berisi kunci "foo".
m.foo:*	Benar jika m berisi kunci "foo".
m.foo:42	Benar jika m.foo adalah 42.

Saat melintasi pesan, kolom hanya dianggap ada jika memiliki nilai non-default.

Batasan

Masing-masing layanan dapat menentukan struktur atau batasan lebih lanjut untuk kueri filter selain yang didefinisikan di sini.

Pesan

REST API Ad Manager mendukung pengurutan pada metode List. Sintaksis untuk kolom orderBy adalah daftar nama kolom yang dipisahkan koma. Contoh: "foo,bar".

Urutan penyortiran {i>default<i} adalah menaik. Untuk menentukan urutan menurun untuk suatu kolom, tambahkan akhiran " desc". Contoh: "foo desc, bar".

Karakter spasi yang redundan dalam sintaksis akan diabaikan. Nilai "foo, bar desc", " foo , bar desc ", dan "foo,bar desc" semuanya setara.

Subkolom ditentukan dengan operator traversal. Contoh: foo.bar atau address.street.