Sebagian besar layanan di Display & Video 360 API menyediakan metode LIST
untuk pengambilan resource secara massal. Metode LIST
ini biasanya mendukung hasil pemfilteran melalui
parameter kueri filter
. Gunakan parameter ini untuk mengoptimalkan penggunaan API hanya dengan mengambil yang Anda butuhkan.
Panduan ini menunjukkan cara menggunakan parameter filter
secara efektif.
Struktur filter
Nilai parameter filter
adalah string, yang terdiri dari satu atau beberapa pembatasan
yang dapat digabungkan dengan operator AND
atau OR
, dan dikelompokkan menggunakan
tanda kurung.
Pembatasan berbentuk {field} {operator} {value}
. Berikut
contohnya:
entityStatus="ENTITY_STATUS_ACTIVE"
Panjang string filter tidak boleh lebih dari 500 karakter. Jika string filter Anda melebihi 500 karakter, lakukan salah satu langkah berikut:
- Bagi logika menjadi beberapa string filter, dan ambil resource menggunakan
permintaan
LIST
terpisah. - Hapus beberapa logika dari string filter, lalu gunakan untuk memfilter resource yang diambil secara lokal.
Gabungkan nilai batasan dalam tanda kutip untuk memastikan logika diterapkan dengan benar.
Enkodekan string filter Anda ke URL jika Anda melakukan panggilan LIST
secara langsung tanpa
menggunakan library klien.
Lihat Logika antar-pembatasan untuk mengetahui detail selengkapnya tentang cara memformat kueri.
Kolom yang dapat difilter
Setiap kolom metode LIST
yang dapat difilter tercantum dalam deskripsi parameter filter
metode. Pada umumnya, Anda dapat memfilter subset kolom standar
resource. Dalam beberapa kasus yang jarang terjadi, ada kolom tambahan yang hanya dapat Anda gunakan untuk pemfilteran.
Setiap kolom dalam deskripsi parameter mendukung setidaknya salah satu operator yang sebanding berikut:
Operator yang Sebanding | ||
---|---|---|
EQUALS (=)
|
Nilai kolom resource sama dengan nilai yang diberikan.
Contoh: |
|
LESS THAN OR EQUAL TO (<=)
|
Nilai kolom resource kurang dari atau sama dengan nilai yang diberikan. Sering digunakan saat membandingkan tanggal atau tanggal & waktu.
Contoh: |
|
GREATER THAN OR EQUAL TO (>=)
|
Nilai kolom resource lebih besar dari atau sama dengan nilai yang diberikan. Sering digunakan saat membandingkan tanggal atau tanggal & waktu.
Contoh: |
|
HAS (:)
|
Nilai kolom resource berisi nilai yang diberikan. Jika kolom resource berupa string, kolom ini akan memeriksa apakah nilai yang diberikan merupakan substring yang sudah ada. Jika kolom resource berupa array, kolom ini akan memeriksa apakah array berisi nilai yang diberikan.
Contoh: |
Jika tidak ada operator yang ditentukan untuk kolom dalam deskripsi parameter, Anda hanya dapat menggunakan operator EQUALS (=)
. Beberapa kolom mendukung beberapa operator.
Beberapa kolom yang dapat difilter, seperti untuk tanggal dan waktu, memerlukan
nilai yang sebanding untuk mengikuti format tertentu. Format tersebut ditentukan di samping
kolom dalam deskripsi parameter filter
.
Logika antar pembatasan
Anda dapat menggabungkan beberapa batasan untuk mempersempit atau memperluas respons dari
permintaan LIST
.
Biasanya, Anda dapat menggabungkan beberapa batasan dengan operator logika
AND
dan OR
. Setiap metode LIST
menentukan operator yang didukungnya.
Beberapa metode hanya mendukung penggunaan satu batasan dalam parameter filter
.
Pertimbangkan batasan berikut saat membuat string filter dengan operator logika AND
atau OR
:
AND
harus digunakan di antara pembatasan, atau grup pembatasan, yang memfilter kolom yang berbeda, atau yang memfilter kolom yang sama secara berbeda. Berikut beberapa contohnya:updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
OR
harus digunakan di antara setiap pembatasan yang memfilter menurut kolom yang sama. Berikut ini contohnya:(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
Anda tidak dapat menggunakan
OR
untuk menggabungkan dua grup pembatasan. Sebagai gantinya, gunakan beberapa permintaanLIST
dengan nilai filter yang berbeda. Misalnya, gunakan permintaanLIST
terpisah berikut:(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
(lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
Jangan gunakan operator
OR
untuk menggabungkannya:(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
Tanda kurung dapat tersirat jika Anda tidak menggunakannya untuk mengelompokkan pembatasan dalam string filter. Misalnya, string filter berikut:
updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"
ditafsirkan sebagai:
updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")