Filter

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

Untuk memulai, berikut 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 URL untuk permintaan GET. Misalnya: String filter: orders.updateTime > "2024-01-01T00:00:00-5:00" URL yang dienkode: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22. Hal ini ditangani secara otomatis oleh library klien.

Literal

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

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

Operator logika

Ad Manager API 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 bernilai benar.

Catatan: Untuk mencocokkan pola ucapan umum, operator OR memiliki prioritas yang lebih tinggi daripada AND, tidak seperti yang ditemukan di 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 API menyediakan operator unary NOT dan -. Kedua namespace 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 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 yang kurang dari 42.
>	a > "foo"	Benar jika a diurutkan secara leksikonis setelah "foo".
<=	a <= "foo"	Benar jika a adalah "foo" atau secara leksikal sebelum itu.
>=	a >= 42	Benar jika a adalah nilai numerik 42 atau lebih tinggi.

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

Karena filter diterima sebagai string kueri, konversi jenis akan dilakukan untuk menerjemahkan string ke nilai strongly-typed 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.
• Angka 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". Selisih waktu UTC didukung.

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

Karakter pengganti

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

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

Operator traversal

Ad Manager 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".

Pelacakan ditulis menggunakan nama kolom dari resource. Setiap layanan dapat menentukan subset kolom yang didukung untuk traversal.

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

Memiliki operator

Ad Manager API mendukung operator :, yang berarti "memiliki". Fungsi 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 sehingga e.foo = 42.

Penting: Filter tidak dapat membuat kueri elemen tertentu pada kolom berulang untuk 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 menjelajahi pesan, kolom hanya dianggap ada jika memiliki nilai non-default.

Batasan

Setiap layanan dapat menentukan struktur atau batasan lebih lanjut untuk kueri filter selain yang ditentukan di sini.

Pesan

Sebagian besar resource mendukung pengurutan pada metode List. Lihat dokumentasi metode List untuk mengetahui perilaku resource yang tepat dan kolom mana yang didukung untuk pengurutan.

Sintaksis untuk kolom orderBy adalah daftar nama kolom yang dipisahkan koma. Contoh: "foo,bar".

Urutan pengurutan default adalah menaik. Untuk menentukan urutan menurun untuk kolom, tambahkan akhiran " desc". Contoh: "foo desc, bar".

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

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