Filter respons daftar

Sebagian besar layanan di Display & Video 360 API menyediakan metode LIST untuk pengambilan resource secara massal. Metode LIST ini biasanya mendukung pemfilteran hasil melalui parameter kueri filter. Gunakan parameter ini untuk mengoptimalkan penggunaan API dengan hanya mengambil hal yang Anda perlukan.

Panduan ini menunjukkan cara menggunakan parameter filter secara efektif.

Struktur filter

Nilai parameter filter adalah string, yang terdiri dari satu atau beberapa batasan yang dapat digabungkan dengan operator AND atau OR, dan dikelompokkan menggunakan tanda kurung.

Batasan memiliki format {field} {operator} {value}. Berikut contohnya:

entityStatus="ENTITY_STATUS_ACTIVE"

Panjang string filter tidak boleh melebihi 500 karakter. Jika string filter Anda melebihi 500 karakter, lakukan salah satu tindakan berikut:

  • Pisahkan logika menjadi beberapa string filter, dan ambil resource menggunakan permintaan LIST terpisah.
  • Hapus beberapa logika dari string filter, dan gunakan untuk memfilter resource yang diambil secara lokal.

Gabungkan nilai batasan dalam tanda kutip untuk memastikan logika diterapkan dengan benar.

Enkode string filter Anda ke dalam URL jika Anda melakukan panggilan LIST secara langsung tanpa menggunakan library klien.

Lihat Logika antara batasan untuk mengetahui detail selengkapnya tentang cara memformat kueri Anda.

Kolom yang dapat difilter

Setiap kolom metode LIST yang dapat difilter tercantum dalam deskripsi parameter filter metode. Dalam sebagian besar kasus, Anda dapat memfilter pada subkumpulan 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: entityStatus="ENTITY_STATUS_ACTIVE"
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: updateTime<="2023-04-01T12:00:00Z"
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: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Nilai kolom resource berisi nilai yang diberikan. Jika kolom resource berupa string, kolom tersebut akan memeriksa apakah nilai yang diberikan adalah substring yang ada. Jika kolom resource adalah array, kolom tersebut akan memeriksa apakah array berisi nilai yang diberikan.

Contoh: lineItemIds:"1234"

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 kolom untuk tanggal dan waktu, memerlukan nilai yang sebanding untuk mengikuti format tertentu. Format ditentukan di samping kolom dalam deskripsi parameter filter.

Logika antara batasan

Anda dapat menggabungkan beberapa batasan untuk mempersempit atau memperluas respons dari permintaan LIST.

Anda biasanya dapat menggabungkan beberapa batasan dengan operator logis 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 batasan, atau grup batasan, 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 batasan yang memfilter menurut kolom yang sama. Berikut adalah 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 batasan. Sebagai gantinya, gunakan beberapa permintaan LIST dengan nilai filter yang berbeda. Misalnya, gunakan permintaan LIST 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 mungkin tersirat jika Anda tidak menggunakannya untuk mengelompokkan batasan 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")