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:
NOT
OR
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. |
|
Bilangan Bulat | Setiap angka yang tidak memiliki titik desimal, dengan atau tanpa tanda ("-") akan diperlakukan sebagai bilangan bulat. |
|
String
Bagian ini menjelaskan jenis yang dapat Anda tulis sebagai literal string dalam sintaksis filter.
Jenis | Definisi | Contoh |
---|---|---|
Boolean | TRUE atau FALSE dalam huruf besar/kecil. |
|
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. |
|
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.
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 denganname
adalah string yang berisi"abcd"
. - Pemeriksaan keberadaan
- Saat Anda menggunakan operator
HAS
dengan karakter khusus*
, operatorHAS
akan memeriksa nilai non-null. Misalnya,name:*
menampilkan semua instance yangname
-nya bukan null, tidak ada, atau belum ditentukan. - Saat Anda menggunakan operator
HAS
dengan nilai non-string, operator tersebut berperilaku sama seperti operatorEQUALS
(=
). Misalnya,isCompleted:true
berperilaku dengan cara yang sama sepertiisCompleted = true
. - Kolom Berulang
Anda dapat menggunakan operator
HAS
(:
) untuk memfilter kolom resource API berulang, selama hal berikut berlaku:- Hanya ada satu komponen berulang di sepanjang jalur ID kolom
- ID terakhir jalur medan adalah jenis skalar
Pemfilteran pada kolom berulang bertingkat tidak didukung.
Berikut contohnya:
item
memiliki kolomcolors
, yang berisi nilai string seperti"red"
,"blue"
, dan"yellow"
.item.colors:("red")
menampilkan semua item yang memiliki nilai"red"
di kolomcolors
.item.colors:("red" "yellow")
menampilkan semua item yang memiliki"red"
dan"yellow"
di kolomcolors
.item.colors:("red" OR "yellow")
menampilkan semua item yang memiliki"red"
atau"yellow"
di kolomcolors
.
item
juga memiliki kolomtools
berulang yang merupakan objek kompleks dengan kolom skalarshape
, 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"
.
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 yang memiliki nilai bilangan bulat 93641. |
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 |
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 tidak sama dengan "proposal". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState memiliki nilai enum yang sama dengan PROPOSED OR BUYER_ dapatkan. |
proposalState = (PROPOSED AND 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 sama dengan "Test1" atau sama dengan "Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName berisi substring "test". |
dealName:("A B") |
dealName berisi substring "A B". |
dealName:(A B) |
dealName berisi substring "A" dan substring "B". |
dealName:("A" OR "B" AND "C") |
dealName berisi substring "A" ATAU "B" DAN juga berisi substring "C" |
dealName:("A B" 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) |
dealName tidak berisi substring "A" dan juga berisi substring "B". |
dealName:(NOT "A" OR "B") |
dealName tidak berisi substring "A" atau mengandung substring "B". |