Mencantumkan sintaksis dan penggunaan filter

Panduan ini menjelaskan sintaksis filter daftar dan cara memfilter berbagai jenis resource.

Beberapa metode API dapat menerima filter untuk membatasi resource yang ditampilkan dalam respons.

Ringkasan

Bagian ini memberikan ringkasan singkat tentang struktur sintaksis filter daftar.

• Filter adalah string yang berisi expression. expression adalah kombinasi Boolean dari perbandingan:

  expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
  expression = ( expression )
  

• comparison cocok dengan kolom resource dengan nilai. Anda dapat menggunakan semua operator perbandingan umum.

  comparison = name OP value
  OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
  

  Operator has, titik dua (:), dapat digunakan pada string dan kolom berulang. Lihat bagian Operator memiliki untuk mengetahui detailnya.

• Anda dapat menggunakan jenis nilai berikut dalam filter:

  • Numbers
  • String
  • Ekspresi yang diberi tanda kurung

  value = number| string | "*" | "(" expression ")"
  

• String dapat mewakili hal berikut:

  • Teks arbitrer
  • Boolean
  • Nilai enum
  • Stempel waktu

Ekspresi Boolean

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

Operasi dilakukan dalam urutan berikut:

1. NOT
2. OR
3. AND

Misalnya, ekspresi berikut adalah setara:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

Anda dapat menghilangkan operator AND di antara perbandingan. Misalnya, filter berikut sama:

c=d AND e=f

c=d e=f

Anda dapat menggunakan tanda hubung (-) sebagai alternatif untuk NOT. Tidak boleh ada spasi antara tanda hubung (-) dan perbandingan berikut. Misalnya, filter berikut sama:

NOT e=f

-e=f

Perbandingan

Bagian ini menjelaskan perbandingan "name OP value" seperti berikut:

comparison = name OP value

dengan

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

Sisi kiri perbandingan adalah nama jalur kolom resource API. Nama ini terdiri dari serangkaian ID resource yang dihubungkan dengan titik (.). Setiap ID kolom diikuti oleh nama level berikutnya untuk kolom tersebut. Misalnya, anggaplah resource yang memiliki kolom kompleks item yang memiliki kolom kompleks tool lainnya, yang memiliki kolom bernama shape. Dalam filter untuk resource ini, Anda akan merujuk ke bentuk dengan nama item.tool.shape.

Sisi kanan biasanya merupakan nilai skalar yang dikonversi ke jenis kolom dan dibandingkan dengannya. Lihat bagian jenis Value Literal untuk detail selengkapnya.

Sisi kanan perbandingan juga dapat dinyatakan sebagai kombinasi Boolean dalam tanda kurung dari nilai literal dan/atau ekspresi boolean yang hanya berisi nilai literal (diawali dengan atau tanpa NOT). Nama sisi kiri dan operator perbandingan diterapkan ke setiap nilai. Misalnya, filter berikut sama:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

Berikut ini contoh lain yang lebih kompleks dari dua filter yang setara:

deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))

(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")

Jenis Literal Nilai

Nilai di sisi kanan operator Perbandingan dapat dikategorikan ke dalam literal Angka dan String.

Angka

Bagian ini menjelaskan representasi literal numerik.

Jenis	Definisi	Contoh
Double	Setiap angka yang berisi titik desimal, dengan atau tanpa tanda ("-") akan diperlakukan sebagai Ganda.	1234.567 -789.0123
Bilangan Bulat	Setiap angka yang tidak memiliki titik desimal, dengan atau tanpa tanda ("-") akan diperlakukan sebagai bilangan bulat.	1234 -789

String

Bagian ini menjelaskan jenis yang dapat Anda tulis sebagai literal string dalam sintaksis filter.

Catatan: literal string dapat diberi tanda kutip ganda (" "), atau tanpa tanda kutip. Anda tidak dapat menggunakan tanda kutip tunggal untuk mewakili literal string. Misalnya, "ABC DEF" dan ABC DEF adalah literal string, tetapi 'ABC DEF' tidak.

Jenis	Definisi	Contoh
Boolean	TRUE atau FALSE dalam huruf besar/kecil.	TRUE True "true"
Enum	Nama literal jenis enumerasi. Enum peka huruf besar/kecil.	FINALIZED tidak sama dengan Finalized
String	String apa pun yang berisi teks berenkode UTF-8 atau 7-bit ASCII. Tanda kutip tersemat harus di-escape dengan garis miring terbalik. String yang tidak dikutip dengan spasi kosong diperlakukan sebagai `AND` implisit di antara semua kata setelah memisahkan string dengan spasi kosong.	name = "test \"double quotes\"" name=(ABC DEF) setara dengan name=ABC AND name=DEF
Stempel waktu	String dalam format standar ISO8601.	"2014-10-02T15:01:23.045Z"

Operator perbandingan

Berikut adalah operator perbandingan:

• Kurang dari atau sama dengan: "<="
• Kurang dari: "<"
• Lebih dari atau sama dengan: ">="
• Lebih dari: ">"
• Tidak sama dengan: "!="
• Sama dengan: "="
• Memiliki: ":"

Operator ini berlaku untuk jenis nilai Ganda, Bilangan Bulat, Boolean, Enum, dan Stempel Waktu.

Catatan: Untuk nilai yang disimpan sebagai string, Anda hanya dapat menggunakan operator "!=", "=", dan ":". Perbandingan string tidak peka huruf besar/kecil.

Memiliki operator

Anda dapat menggunakan operator HAS (:) untuk operasi khusus pada kolom berikut:

Substring

Jika operator HAS digunakan untuk membandingkan nilai di kolom string dengan string, operator akan bertindak sebagai operasi substring. Misalnya, name:"abcd" menampilkan semua instance dengan name adalah string yang berisi "abcd".

Pemeriksaan keberadaan

Saat Anda menggunakan operator HAS dengan karakter khusus *, operator HAS akan memeriksa nilai non-null. Misalnya, name:* menampilkan semua instance yang name-nya bukan null, tidak ada, atau belum ditentukan.

Saat Anda menggunakan operator HAS dengan nilai non-string, operator tersebut berperilaku sama seperti operator EQUALS (=). Misalnya, isCompleted:true berperilaku dengan cara yang sama seperti isCompleted = true.

Kolom Berulang

Anda dapat menggunakan operator HAS (:) untuk memfilter kolom resource API berulang, selama hal berikut berlaku:

1. Hanya ada satu komponen berulang di sepanjang jalur ID kolom
2. ID terakhir jalur medan adalah jenis skalar

Pemfilteran pada kolom berulang bertingkat tidak didukung.

Berikut contohnya:

item memiliki kolom colors, yang berisi nilai string seperti "red", "blue", dan "yellow".

• item.colors:("red") menampilkan semua item yang memiliki nilai "red" di kolom colors.
• item.colors:("red" "yellow") menampilkan semua item yang memiliki "red" dan "yellow" di kolom colors.
• item.colors:("red" OR "yellow") menampilkan semua item yang memiliki "red" atau "yellow" di kolom colors.

item juga memiliki kolom tools berulang yang merupakan objek kompleks dengan kolom skalar shape, yang nilainya dapat berupa "square" atau "round".

• item.tools.shape:("square") menampilkan semua item yang memiliki alat berbentuk "square".
• item.tools.shape:("square" "round") menampilkan semua item yang memiliki alat berbentuk "square" dan alat berbentuk "round".
• item.tools.shape:("square" OR "round") menampilkan semua item yang memiliki alat bentuk "square" atau alat berbentuk "round".

Catatan: Tidak semua kolom berulang dapat difilter. Untuk mengetahui detail selengkapnya tentang resource tertentu, lihat dokumentasi referensi.

Kolom bertingkat yang tidak terisi

Kolom bertingkat adalah sub-kolom dari kolom tingkat root, misalnya shape di item.tools.shape adalah kolom bertingkat dari items.tools.

Kolom tingkat root ditetapkan secara default ke salah (false). Kolom bertingkat tidak diisi secara default.

Objek dengan kolom bertingkat yang tidak terisi tidak ditampilkan oleh filter negatif (!=).

Berikut contohnya:

item.tools memiliki enum size yang nilainya dapat ditetapkan ke "SMALL", "MEDIUM", atau "LARGE".

Jika Anda memiliki item berikut:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

Panggilan ke items.list dengan filter negatif "tools.size != SMALL" akan menampilkan hal berikut:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

Karena item.tools.size belum ditetapkan untuk item3, filter negatif tidak menampilkan objek item3.

Contoh

Contoh	Deskripsi
externalDealId = "123456789"	externalDealId yang memiliki nilai string "123456789".
advertiserId:93641 advertiserId = 93641	advertiserId yang memiliki nilai bilangan bulat 93641.
isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)	isSetupComplete sama dengan TRUE.
updateTime > "2018-02-14T11:09:19.378Z"	updateTime lebih lambat dari 14/02/2018 11:09:19.378 UTC
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	String displayName memiliki nilai "proposal" yang identik DAN proposalRevisi sama dengan 3.
displayName = "proposal" OR proposalRevision = 3	displayName memiliki nilai string "proposal" ATAU proposalRevisi sama dengan 3.
NOT displayName = "proposal" displayName != "proposal"	displayName tidak sama dengan "proposal".
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState memiliki nilai enum yang sama dengan PROPOSED OR BUYER_ dapatkan.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	proposalState memiliki nilai enum yang sama dengan PROPOSED AND BUYER_ dapatkan
dealName = Test Deal	INVALID ekspresi
dealName = "Test Deal"	dealName sama dengan "Test Deal".
dealName = (Test Deal)	dealName sama dengan "Test" dan juga sama dengan "Deal".
dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"	dealName sama dengan "Test1" atau sama dengan "Test2".
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName berisi substring "test".
dealName:("A B") dealName:"A B"	dealName berisi substring "A B".
dealName:(A B) dealName:"A" AND dealName:"B"	dealName berisi substring "A" dan substring "B".
dealName:("A" OR "B" AND "C") dealName:("A" OR "B" "C") dealName:"A" OR dealName:"B" AND dealName:"C" dealName:"A" OR dealName:"B" dealName:"C" (dealName:"A" OR dealName:"B") AND dealName:"C" (dealName:"A" OR dealName:"B") dealName:"C"	dealName berisi substring "A" ATAU "B" DAN juga berisi substring "C"
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName berisi substring "A B" dan juga berisi substring "C".
dealName:("A B" OR C D)	dealName berisi substring "A B" atau "C", dan juga berisi substring "D".
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName tidak berisi substring "A" dan juga berisi substring "B".
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName tidak berisi substring "A" atau mengandung substring "B".