列出篩選器語法和用法

本指南將說明清單篩選器語法，以及如何篩選各種資源類型。

部分 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}

作業會按照以下順序完成：

1. NOT
2. OR
3. 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 運算子的右側值可分為數字和字串常值。

編號

本節說明數字常值的表示法。

類型	定義	範例
二壘安打	凡是包含小數點的數字 (無論是否有符號「-」)，一律都會視為雙精度浮點值。	1234.567 -789.0123
整數	沒有小數點的任何數字 (無論是否有符號「-」) 都會視為整數。	1234 -789

字串

本節說明可以使用篩選器語法編寫為字串常值的類型。

注意： 字串常值可以是雙引號 (" ") 或未加引號。您無法使用單引號代表字串常值。舉例來說，「ABC DEF」和 ABC DEF 是字串常值，但「ABC DEF」不是。

類型	定義	範例
布林值	TRUE 或 FALSE (大寫)	TRUE True "true"
列舉	列舉類型常值的名稱。列舉區分大小寫。	FINALIZED 與 Finalized 不同
字串	包含 UTF-8 編碼或 7 位元 ASCII 文字的任何字串。內嵌引號必須使用反斜線逸出。以空白字元分割字串後，系統會將含有空格的未加引號字串視為隱含的「AND」。	name = "test \"double quotes\"" name=(ABC DEF) 相當於 name=ABC AND name=DEF
時間戳記	採用 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 資源欄位，前提是必須符合以下條件：

1. 欄位 ID 路徑中只有一個重複元件
2. 欄位路徑的最後一個 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	advertiserId，整數值 93641。
isSetupComplete = true isSetupComplete:TRUE 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」值相同，而且 ProposalRevision 等於 3。
displayName = "proposal" OR proposalRevision = 3	displayName 的字串值為「proposal」，或是提案修訂版本等於 3。
NOT displayName = "proposal" displayName != "proposal"	displayName 不等於「提案」。
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState 的列舉值等於 PROPOSED 或 BUYER_acceptED。
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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" OR dealName = "Test2"	dealName 等於「Test1」或「Test2」。
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName 包含子字串「test」。
dealName:("A B") dealName:"A B"	dealName 包含子字串「A B」。
dealName:(A B) dealName:"A" AND dealName:"B"	dealName 包含子字串「A」和子字串「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 包含子字串「A」或 "B"，且同時包含子字串「C」
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName 包含子字串「A B」，同時包含子字串「C」。
dealName:("A B" OR C D)	dealName 包含子字串「A B」或「C」，且同時包含子字串「D」。
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName 不含任何子字串「A」，也包含子字串「B」。
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName 不含任何子字串「A」或包含子字串「B」。