Filter respons daftar

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: 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 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: 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 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 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 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")