本頁面由 Cloud Translation API 翻譯而成。

列出篩選器語法和用法

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

某些 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	1234.567 2012 年 7 月 789 日
整數	不含小數點的數字 (不論是否帶符號) (「-」) 將視為整數。	1234 -789

字串

本節會說明您可以在篩選語法。

類型	定義	範例
布林值	`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"`

比較運算子

以下是比較運算子：

小於或等於："<="
小於："<"
大於或等於：">="
大於：">"
不等於："!="
等於："="
包含：":"

這些運算子適用於雙精度浮點值、整數值、布林值、列舉值和時間戳記值。

有運算子

您可以使用 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`	`advertiserId` 是整數值 93641。
`isSetupComplete = true isSetupComplete:TRUE 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 = "proposal" proposalRevision = 3`	`displayName` 字串的值與「提案」相同「同時」提案修訂等於 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` 等於「Test」而且等於「交易」
`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"。