本指南將說明清單篩選器語法,以及如何篩選各種 資源類型
某些 API 方法可接受篩選器,限制 回應。
摘要
本節提供清單篩選器語法結構的快速總覽。
篩選器是包含
expression
的字串。expression
是布林值 綜合評估:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
符合資源欄位與值。您可以使用 常見的比較運算子comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
has
運算子和冒號 (:
),可用於字串並重複 只要使用來自這些領域的 小型資料集訓練即可詳情請參閱「含有運算子」一節。您可以在篩選器中使用以下類型的值:
- Numbers
- 字串
- 加括號的運算式
value = number| string | "*" | "(" expression ")"
字串可以代表下列內容:
- 任意文字
- 布林值
- 列舉值
- 時間戳記
布林運算式
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
作業會按照以下順序完成:
NOT
OR
AND
例如,以下運算式相等:
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
您可以忽略比較之間的 AND
運算子。例如,下列
篩選器是相同的:
c=d AND e=f
c=d e=f
您可以使用連字號 (-
) 做為 NOT
的替代方案。不得使用
連字號 (-
) 和下列比較項目之間的空格。舉例來說,
以下篩選器是相同的:
NOT e=f
-e=f
比較項目
本節將說明 "name OP value"
比較項目,如下所示:
comparison = name OP value
媒介
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
比較的左側是 API 資源欄位的路徑名稱。
名稱包含一系列依句號 (.
) 連接的資源 ID。
每個欄位 ID 後面都會接在該欄位的下一層名稱。適用對象
舉例來說,假設某項資源的複雜欄位 item
有另一個
複雜欄位 tool
,其中包含名為 shape
的欄位。在這個篩選器中
資源,您就會使用名稱為 item.tool.shape
的形狀。
右側通常為純量值,會轉換為欄位的 並進行比較請參閱值常值類型 一節。
比較右側也可以表示為括號內的布林值
僅包含常值和/或布林值運算式的組合
常值 (前面加上或不含 NOT
)。左側名稱和
每個值都會套用比較運算子。舉例來說,
以下篩選器是相同的:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
接著再來看另一個較複雜的範例 篩選器:
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")
值常值類型
比較運算子的右側值可分為「數字」和 字串常值。
數字
本節說明數字常值的表示法。
類型 | 定義 | 範例 |
---|---|---|
雙人床 | 任何包含小數點的數字 (無論是否有符號 (「-」) 會視為 Double |
|
整數 | 不含小數點的數字 (不論是否帶符號) (「-」) 將視為整數。 |
|
字串
本節會說明您可以在 篩選語法。
類型 | 定義 | 範例 |
---|---|---|
布林值 | TRUE 或 FALSE (不區分大小寫)。 |
|
列舉 | 列舉類型常值的名稱。列舉會區分大小寫。 |
FINALIZED 與Finalized 不同
|
字串 | 包含 UTF-8 編碼或 7 位元 ASCII 文字的任何字串。 內嵌引號必須使用反斜線逸出。 系統會將含有空白字元的未加引號字串視為隱含的 `AND` 。 |
|
時間戳記 | ISO8601 標準格式的字串。 |
"2014-10-02T15:01:23.045Z"
|
比較運算子
以下是比較運算子:
- 小於或等於:
"<="
- 小於:
"<"
- 大於或等於:
">="
- 大於:
">"
- 不等於:
"!="
- 等於:
"="
- 包含:
":"
這些運算子適用於雙精度浮點值、整數值、布林值、列舉值和時間戳記值 。
有運算子
您可以使用 HAS
運算子 (:
) 執行下列特殊作業:
欄位:
- 子字串
- 使用
HAS
運算子來比較字串資料欄與 字串,運算子會做為子字串作業。例如:name:"abcd"
會傳回所有例項,其中name
是包含name
的字串"abcd"
。 - 存在檢查
- 將
HAS
運算子與特殊字元*
搭配使用時,HAS
運算子會檢查非空值。例如:name:*
會傳回name
不是空值、遺漏或未定義的所有例項。 ,瞭解如何調查及移除這項存取權。
- 搭配使用
HAS
運算子和非字串值時,運作方式與EQUALS
(=
) 運算子。舉例來說,isCompleted:true
會在 與isCompleted = true
相同 - 重複欄位
您可以使用
HAS
(:
) 運算子篩選重複的 API 資源 ] 欄位,只要以下為 true 即可:- 欄位 ID 路徑只有一個重複元件
- 欄位路徑的最後一個 ID 是純量類型
系統不支援篩選巢狀重複欄位。
範例如下:
item
有colors
欄位,其中包含"red"
、"blue"
和"yellow"
。item.colors:("red")
會傳回所有出現在"red"
值colors
欄位。item.colors:("red" "yellow")
會傳回同時包含"red"
和"yellow"
輸入colors
。item.colors:("red" OR "yellow")
會傳回所有含有"red"
或"yellow"
輸入colors
。
item
也具有重複的tools
欄位,該欄位是具有純量的複雜物件 欄位shape
,其值可以是"square"
或"round"
。item.tools.shape:("square")
會傳回所有形狀為"square"
的項目 工具。item.tools.shape:("square" "round")
會傳回同時擁有"square"
形狀工具和"round"
形狀工具。item.tools.shape:("square" OR "round")
會傳回含有"square"
圖形工具或"round"
形狀工具。
未填入的巢狀欄位
巢狀欄位是根層級欄位的子欄位,例如 shape
item.tools.shape
是 items.tools
的巢狀欄位。
根層級欄位預設為 false。根據預設,系統不會填入巢狀欄位。
含有未填入巢狀欄位的物件不會以負數傳回
篩選器 (!=
)。
範例如下:
item.tools
的 size
列舉值可設為 "SMALL"
、"MEDIUM"
、
或 "LARGE"
。
如果您已經有下列項目:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
包含排除篩選器 "tools.size != SMALL"
的 items.list
呼叫會傳回
包括:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
由於item3
未設定「item.tools.size
」,因此排除篩選器並未
會傳回 item3
物件。
範例
範例 | 說明 |
---|---|
externalDealId = "123456789" |
externalDealId ,包含字串值「123456789」。 |
advertiserId:93641 |
advertiserId 是整數值 93641。 |
isSetupComplete = true |
isSetupComplete 等於 TRUE。 |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime 晚於世界標準時間 2018 年 02/14 11:09:19.378 |
displayName = "proposal" AND proposalRevision = 3 |
displayName 字串的值與「提案」相同「同時」提案修訂等於 3。 |
displayName = "proposal" OR proposalRevision = 3 |
「displayName 」的字串值是「proposal」或者提案修訂版本為 3。 |
NOT displayName = "proposal" |
displayName 不等於「提案」。 |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState 的列舉值等於 PROPOSED 或 BUYER_ACCEPTED。 |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState 的列舉值等於 PROPOSED AND BUYER_ACCEPTED |
dealName = Test Deal |
INVALID 運算式 |
dealName = "Test Deal" |
dealName 等於「測試交易」。 |
dealName = (Test Deal) |
dealName 等於「Test」而且等於「交易」 |
dealName = ("Test1" OR "Test2") |
dealName 等於「Test1」或等於「Test2」。 |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName 包含子字串「test」。 |
dealName:("A B") |
dealName 包含子字串「A B」。 |
dealName:(A B) |
dealName 包含子字串「A」以及子字串「B」 |
dealName:("A" OR "B" AND "C") |
dealName 包含子字串「A」或「B」且也包含子字串「C」 |
dealName:("A B" C) |
dealName 包含子字串「A B」且包含子字串「C」。 |
dealName:("A B" OR C D) |
dealName 包含子字串「A B」或「C」,而且也包含子字串「D」。 |
dealName:(NOT "A" B) |
dealName 不含任何子字串「A」且包含子字串「B」。 |
dealName:(NOT "A" OR "B") |
dealName 不含任何子字串「A」,或是包含子字串 "B"。 |