Filter respons daftar

Sebagian besar layanan di Display & Video 360 API menyediakan metode LIST untuk pengambilan massal Google Cloud Platform. Metode LIST ini biasanya mendukung hasil pemfilteran melalui Parameter kueri filter. Gunakan parameter ini untuk mengoptimalkan penggunaan API Anda hanya dengan mendapatkan apa 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 batasan 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 melebihi 500 karakter, lakukan salah satu hal berikut:

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

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

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

Lihat Logika antar-pembatasan untuk detail selengkapnya tentang pemformatan kueri Anda.

Kolom yang dapat difilter

Setiap kolom yang dapat difilter dari metode LIST tercantum dalam filter metode deskripsi parameter. Dalam kebanyakan kasus, Anda dapat memfilter pada subset {i>field<i} standar. Dalam beberapa kasus yang jarang terjadi, ada kolom tambahan yang dapat Anda gunakan hanya untuk pemfilteran.

Setiap kolom dalam deskripsi parameter mendukung setidaknya salah satu hal berikut operator yang sebanding:

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 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 ruang isian resource adalah {i>string<i}, ia akan memeriksa apakah nilai yang diberikan adalah {i>substring<i} yang sudah ada. Jika isian sumber daya adalah himpunan (array), ini akan memeriksa apakah himpunan (array) berisi nilai yang diberikan dengan sejumlah nilai.

Contoh: lineItemIds:"1234"

Jika tidak ada operator yang ditentukan untuk kolom dalam deskripsi parameter, Anda hanya dapat menggunakan operator EQUALS (=). Beberapa kolom mendukung lebih dari satu operator.

Beberapa kolom yang dapat difilter, seperti kolom untuk tanggal dan waktu, memerlukan nilai yang sebanding untuk mengikuti format tertentu. Format ini ditentukan di samping kolom di 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 AND dan OR operator logika. 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 AND atau operator logika OR:

  • AND harus digunakan di antara batasan, atau kelompok 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 batasan individual yang memfilter menurut kolom tersebut. Berikut 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 kelompok pembatasan. Gunakan beberapa LIST permintaan 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 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")