本指南將說明清單篩選器語法,以及如何篩選各種資源類型。
部分 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")
值常值類型
Comparison 運算子的右側值可分為數字和字串常值。
編號
本節說明數字常值的表示法。
類型 | 定義 | 範例 |
---|---|---|
二壘安打 | 凡是包含小數點的數字 (無論是否有符號「-」),一律都會視為雙精度浮點值。 |
|
整數 | 沒有小數點的任何數字 (無論是否有符號「-」) 都會視為整數。 |
|
字串
本節說明可以使用篩選器語法編寫為字串常值的類型。
類型 | 定義 | 範例 |
---|---|---|
布林值 | TRUE 或 FALSE (大寫) |
|
列舉 | 列舉類型常值的名稱。列舉區分大小寫。 |
FINALIZED 與 Finalized 不同
|
字串 | 包含 UTF-8 編碼或 7 位元 ASCII 文字的任何字串。內嵌引號必須使用反斜線逸出。以空白字元分割字串後,系統會將含有空格的未加引號字串視為隱含的「AND」。 |
|
時間戳記 | 採用 ISO8601 標準格式的字串。 |
"2014-10-02T15:01:23.045Z"
|
比較運算子
以下介紹比較運算子:
- 小於或等於:
"<="
- 小於:
"<"
- 大於或等於:
">="
- 大於:
">"
- 不等於:
"!="
- 等於:
"="
- 擁有:
":"
這些運算子適用於 Double、Integer、Boolean、Enum 和時間戳記值類型。
有運算子
您可以在下列欄位使用 HAS
運算子 (:
) 進行特殊作業:
- 子字串
- 使用
HAS
運算子將字串資料欄的值與字串進行比較時,該運算子會做為子字串作業。舉例來說,name:"abcd"
會傳回所有例項,其中name
是包含"abcd"
的字串。 - 存在檢查
- 使用
HAS
運算子搭配特殊字元*
時,HAS
運算子會檢查是否有非空值。舉例來說,name:*
會傳回name
並非空值、遺漏或未定義的所有例項。 - 使用
HAS
運算子搭配非字串值時,其行為與EQUALS
(=
) 運算子相同。舉例來說,isCompleted:true
的行為與isCompleted = true
相同。 - 重複欄位
您可以使用
HAS
(:
) 運算子篩選重複的 API 資源欄位,前提是必須符合以下條件:- 欄位 ID 路徑中只有一個重複元件
- 欄位路徑的最後一個 ID 是純量類型
系統不支援篩選巢狀的重複欄位。
範例如下:
item
有colors
欄位,其中包含"red"
、"blue"
和"yellow"
等字串值。item.colors:("red")
會傳回colors
欄位中含有"red"
值的所有項目。item.colors:("red" "yellow")
會傳回colors
欄位中同時含有"red"
和"yellow"
的所有項目。item.colors:("red" OR "yellow")
會傳回colors
欄位中含有"red"
或"yellow"
的所有項目。
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"
形狀工具的項目。
未填入的巢狀欄位
巢狀欄位是根層級欄位的子欄位,例如 item.tools.shape
中的 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" |
包含字串值「123456789」的 externalDealId 。 |
advertiserId:93641 |
advertiserId ,整數值 93641。 |
isSetupComplete = true |
isSetupComplete 等於 TRUE。 |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime 晚於世界標準時間 2018 年 2 月 14 日 11:09:19.378 |
displayName = "proposal" AND proposalRevision = 3 |
displayName 字串的「proposal」值相同,而且 ProposalRevision 等於 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 等於「測試」,也等於「交易」。 |
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」。 |