Panduan ini menjelaskan {i>syntax<i} filter daftar dan cara memfilter berbagai jenis resource.
Beberapa metode API bisa menerima filter untuk membatasi resource yang ditampilkan dalam yang dihasilkan.
Ringkasan
Bagian ini memberikan ringkasan singkat tentang struktur sintaksis daftar filter.
Filter adalah string yang berisi
expression
.expression
adalah Boolean kombinasi perbandingan:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
cocok dengan kolom resource dengan nilai. Anda dapat menggunakan semua operator perbandingan yang umum.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
Operator
has
, titik dua (:
), dapat digunakan pada string dan kolom. Lihat bagian Memiliki operator untuk mengetahui detailnya.Anda dapat menggunakan jenis nilai berikut dalam filter:
- Angka
- String
- Ekspresi dalam 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,
filternya 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
di mana
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
Sisi kiri perbandingan adalah nama jalur kolom resource API.
Nama terdiri dari serangkaian ID resource yang dihubungkan berdasarkan titik (.
).
Setiap ID kolom diikuti dengan nama tingkat berikutnya untuk kolom tersebut. Sebagai
sebagai contoh, pertimbangkan resource yang memiliki kolom kompleks item
yang memiliki
kolom kompleks tool
yang memiliki kolom bernama shape
. Di filter untuk ini
resource, Anda akan merujuk pada bentuk dengan nama item.tool.shape
.
Sisi kanan biasanya merupakan nilai skalar yang dikonversi menjadi sisi dan membandingkannya. Lihat jenis Literal Nilai untuk detail selengkapnya.
Sisi kanan perbandingan juga dapat dinyatakan sebagai Boolean dalam tanda kurung
kombinasi 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 contoh yang setara filter:
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 sisi kanan operator Perbandingan dapat dikategorikan ke dalam Angka dan Literal string.
Angka
Bagian ini menjelaskan representasi literal numerik.
Jenis | Definisi | Contoh |
---|---|---|
Ganda | Setiap angka yang berisi titik desimal, dengan atau tanpa tanda ("-") diperlakukan sebagai Ganda. |
|
Bilangan Bulat | Setiap angka yang tidak memiliki titik desimal, dengan atau tanpa tanda ("-") 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 kapitalisasi huruf apa pun. |
|
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 ASCII 7-bit. Tanda petik 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 nilai Ganda, Bilangan Bulat, Boolean, Enum, dan Stempel Waktu jenis datanya.
Memiliki operator
Anda dapat menggunakan operator HAS
(:
) untuk operasi khusus pada
bidang:
- Substring
- Saat operator
HAS
digunakan untuk membandingkan nilai pada kolom string dengan {i>string<i}, operator akan bertindak sebagai operasi substring. Misalnya,name:"abcd"
menampilkan semua instance denganname
sebagai string yang berisi"abcd"
. - Pemeriksaan keberadaan
- Saat Anda menggunakan operator
HAS
dengan karakter khusus*
, operatorHAS
memeriksa nilai {i>non-null<i}. Misalnya,name:*
menampilkan semua instance jikaname
bukan null, tidak ada, atau tidak ditentukan. - Saat Anda menggunakan operator
HAS
dengan nilai non-string, operator tersebut akan berperilaku sama seperti operatorEQUALS
(=
). Misalnya,isCompleted:true
berperilaku di dengan cara yang sama sepertiisCompleted = true
. - Kolom Berulang
Anda dapat menggunakan operator
HAS
(:
) untuk memfilter resource API berulang selama hal berikut terpenuhi:- Hanya ada satu komponen berulang di sepanjang jalur ID kolom
- ID terakhir jalur kolom 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"
dalam 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 skalar kolomshape
, yang nilainya dapat berupa"square"
atau"round"
.item.tools.shape:("square")
menampilkan semua item yang berbentuk"square"
alat.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 false (salah). Kolom bertingkat tidak diisi secara default.
Objek dengan kolom bertingkat yang tidak terisi tidak ditampilkan dengan nilai negatif
filter (!=
).
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 ditampilkan
hal berikut:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Karena item.tools.size
belum ditetapkan untuk item3
, filter negatif tidak
tampilkan 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 adalah lebih dari 02/14/2018 11:09:19.378 UTC |
displayName = "proposal" AND proposalRevision = 3 |
String displayName memiliki nilai "proposal" yang identik DAN proposalRevision sama dengan 3. |
displayName = "proposal" OR proposalRevision = 3 |
displayName memiliki nilai string "proposal" ATAU proposalRevision 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_ENABLED. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState memiliki nilai enum yang sama dengan PROPOSED DAN PURCHASE_ Penerapan |
dealName = Test Deal |
Ekspresi INVALID |
dealName = "Test Deal" |
dealName sama dengan "Transaksi Uji". |
dealName = (Test Deal) |
dealName sama dengan "Test" dan juga sama dengan "Transaksi". |
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 {i>substring<i} "B". |
dealName:("A" OR "B" AND "C") |
dealName berisi salah satu substring "A" ATAU "B" AND juga berisi {i>substring<i} "C" |
dealName:("A B" C) |
dealName berisi substring "A B" dan juga berisi {i>substring<i} "C". |
dealName:("A B" OR C D) |
dealName berisi substring "A B" atau “C”, dan juga berisi {i>substring<i} “D”. |
dealName:(NOT "A" B) |
dealName tidak berisi substring "A" dan juga berisi {i>substring<i} "B". |
dealName:(NOT "A" OR "B") |
dealName tidak berisi substring "A" atau mengandung {i>substring<i} "B". |