Trang này được dịch bởi Cloud Translation API.

Cú pháp và cách sử dụng bộ lọc danh sách

Hướng dẫn này mô tả cú pháp của bộ lọc danh sách và cách lọc nhiều loại tài nguyên.

Một số phương thức API có thể chấp nhận bộ lọc để giới hạn các tài nguyên được trả về trong phản hồi.

Tóm tắt

Phần này cung cấp thông tin tổng quan ngắn gọn về cấu trúc cú pháp của bộ lọc danh sách.

Bộ lọc là một chuỗi chứa expression. expression là một tổ hợp Boolean của các phép so sánh:
```
expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
expression = ( expression )
```
comparison khớp với trường tài nguyên với một giá trị. Bạn có thể sử dụng tất cả các toán tử so sánh phổ biến.
```
comparison = name OP value
OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
```
Bạn có thể dùng toán tử has, dấu hai chấm (:), trên các chuỗi và trường lặp lại. Hãy xem phần Có toán tử để biết thông tin chi tiết.
Bạn có thể sử dụng các loại giá trị sau trong bộ lọc:
- Numbers
- Chuỗi
- Biểu thức trong ngoặc đơn
```
value = number| string | "*" | "(" expression ")"
```
Các chuỗi có thể biểu thị những nội dung sau:
- Văn bản tuỳ ý
- Boolean
- Giá trị enum
- Dấu thời gian

Biểu thức boolean

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

Các thao tác được thực hiện theo thứ tự sau:

NOT
OR
AND

Ví dụ: các biểu thức sau đây tương đương với nhau:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

Bạn có thể bỏ qua toán tử AND giữa các phép so sánh. Ví dụ: các bộ lọc sau đây giống nhau:

c=d AND e=f

c=d e=f

Bạn có thể sử dụng dấu gạch nối (-) để thay thế cho NOT. Không được có dấu cách giữa dấu gạch nối (-) và phép so sánh sau. Ví dụ: các bộ lọc sau đây giống nhau:

NOT e=f

-e=f

Phép so sánh

Phần này mô tả thông tin so sánh "name OP value" như sau:

comparison = name OP value

trong đó

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

Phần bên trái của phần so sánh là tên đường dẫn của một trường tài nguyên API. Tên bao gồm một loạt giá trị nhận dạng tài nguyên kết nối với nhau bằng dấu chấm (.). Theo sau mỗi giá trị nhận dạng trường là cấp tên tiếp theo của trường đó. Chẳng hạn, hãy xem xét một tài nguyên có một trường phức tạp item, trong đó có một trường phức tạp khác tool, có một trường tên là shape. Trong bộ lọc cho tài nguyên này, bạn sẽ tham chiếu đến hình dạng có tên là item.tool.shape.

Phía bên phải thường là một giá trị vô hướng được chuyển đổi thành loại của trường và so sánh với giá trị đó. Hãy xem phần Các loại Giá trị cố định để biết thêm thông tin chi tiết.

Phần bên phải của phép so sánh cũng có thể được biểu thị dưới dạng một tổ hợp Boolean có dấu ngoặc đơn của các giá trị cố định và/hoặc biểu thức boolean chỉ chứa các giá trị cố định (đứng trước hoặc không có NOT). Tên bên trái và toán tử so sánh được áp dụng cho từng giá trị. Ví dụ: các bộ lọc sau đây giống nhau:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

Sau đây là một ví dụ khác phức tạp hơn về 2 bộ lọc tương đương:

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")

Các loại giá trị cố định

Bạn có thể phân loại giá trị phía bên phải của toán tử So sánh thành giá trị cố định Số và Chuỗi.

Số

Phần này mô tả cách trình bày giá trị cố định dạng số.

Loại	Định nghĩa	Ví dụ
Số thực có độ chính xác kép	Bất kỳ số nào chứa dấu thập phân, có hoặc không có dấu ("-") đều được coi là Kép.	1234.567 -789.0123
Số nguyên	Mọi số không có dấu thập phân, có hoặc không có dấu ("-") đều được coi là số nguyên.	1234 -789

Chuỗi

Phần này mô tả các loại mà bạn có thể viết dưới dạng giá trị cố định kiểu chuỗi trong cú pháp bộ lọc.

Loại	Định nghĩa	Ví dụ
Boolean	`TRUE` hoặc `FALSE`, bất kỳ kiểu viết hoa chữ cái nào.	`TRUE` `True` `"true"`
Liệt kê	Tên của một kiểu enum. Enum phân biệt chữ hoa chữ thường.	`FINALIZED` không giống với `Finalized`
Chuỗi	Bất kỳ chuỗi nào chứa văn bản mã hoá UTF-8 hoặc 7-bit ASCII. Trong dấu ngoặc kép phải đi kèm với dấu gạch chéo ngược. Các chuỗi không có khoảng trắng trong dấu ngoặc kép được coi là "AND" ngầm ẩn trong số tất cả các từ sau khi tách chuỗi theo khoảng trắng.	`name = "test \"double quotes\""` `name=(ABC DEF)` tương đương với `name=ABC AND name=DEF`
Dấu thời gian	Một chuỗi ở định dạng chuẩn ISO8601.	`"2014-10-02T15:01:23.045Z"`

Toán tử so sánh

Sau đây là các toán tử so sánh:

Ít hơn hoặc bằng: "<="
Ít hơn: "<"
Lớn hơn hoặc bằng: ">="
Lớn hơn: ">"
Không bằng: "!="
Bằng: "="
Có: ":"

Những toán tử này áp dụng cho các loại giá trị Kép, Số nguyên, Boolean, Enum và Dấu thời gian.

Có toán tử

Bạn có thể dùng toán tử HAS (:) cho các thao tác đặc biệt trên các trường sau:

Chuỗi con

Khi dùng toán tử HAS để so sánh các giá trị trên một cột chuỗi với một chuỗi, toán tử này sẽ đóng vai trò là toán tử của chuỗi con. Ví dụ: name:"abcd" trả về tất cả các thực thể trong đó name là một chuỗi chứa "abcd".

Đang kiểm tra tình trạng tồn tại

Khi bạn dùng toán tử HAS với ký tự đặc biệt *, toán tử HAS sẽ kiểm tra các giá trị khác rỗng. Ví dụ: name:* trả về tất cả các thực thể mà name không có giá trị rỗng, bị thiếu hoặc không xác định.

Khi bạn sử dụng toán tử HAS với giá trị không phải chuỗi, toán tử này sẽ hoạt động giống như toán tử EQUALS (=). Ví dụ: isCompleted:true hoạt động theo cách giống như isCompleted = true.

Các trường lặp lại

Bạn có thể sử dụng toán tử HAS (:) để lọc trên một trường tài nguyên API lặp lại, miễn là những điều sau đây là đúng:

Chỉ có một thành phần lặp lại dọc theo đường dẫn giá trị nhận dạng trường
Giá trị nhận dạng cuối cùng của đường dẫn trường thuộc loại vô hướng

Không hỗ trợ lọc trên các trường lặp lại lồng nhau.

Ví dụ:

item có một trường colors chứa các giá trị chuỗi như "red", "blue" và "yellow".

item.colors:("red") trả về tất cả các mục có giá trị "red" trong trường colors.
item.colors:("red" "yellow") trả về tất cả các mục có cả "red" và "yellow" trong trường colors.
item.colors:("red" OR "yellow") trả về tất cả các mục có "red" hoặc "yellow" trong trường colors.

item cũng có một trường tools lặp lại. Đây là một đối tượng phức tạp với trường vô hướng shape. Các giá trị này có thể là "square" hoặc "round".

item.tools.shape:("square") trả về tất cả các mục có các công cụ có hình dạng "square".
item.tools.shape:("square" "round") trả về tất cả các mục có cả công cụ có hình dạng "square" và công cụ có hình dạng "round".
item.tools.shape:("square" OR "round") trả về tất cả các mục có công cụ hình dạng "square" hoặc công cụ hình dạng "round".

Đã bỏ điền các trường lồng nhau

Trường lồng nhau là trường con của trường cấp cơ sở, ví dụ: shape trong item.tools.shape là trường lồng nhau của items.tools.

Trường cấp cơ sở được mặc định là false. Theo mặc định, các trường lồng nhau sẽ không được điền.

Các đối tượng có các trường lồng nhau chưa được điền sẽ không được bộ lọc phủ định (!=) trả về.

Ví dụ:

item.tools có một enum size có giá trị có thể được đặt thành "SMALL", "MEDIUM", hoặc "LARGE".

Nếu bạn có các mặt hàng sau:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

Lệnh gọi đến items.list với bộ lọc phủ định "tools.size != SMALL" sẽ trả về kết quả sau:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

Vì bạn chưa đặt item.tools.size cho item3, nên bộ lọc phủ định không trả về đối tượng item3.

Ví dụ

Ví dụ:	Nội dung mô tả
`externalDealId = "123456789"`	`externalDealId` có giá trị chuỗi là "123456789".
`advertiserId:93641 advertiserId = 93641`	`advertiserId` có giá trị số nguyên 93641.
`isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)`	`isSetupComplete` bằng TRUE.
`updateTime > "2018-02-14T11:09:19.378Z"`	`updateTime` trễ hơn 11:09:19.378 giờ UTC ngày 14/02/2018
`displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3`	Chuỗi `displayName` có giá trị "đề xuất" giống hệt và "đề xuất sửa đổi" bằng 3.
`displayName = "proposal" OR proposalRevision = 3`	`displayName` có giá trị chuỗi là "đề xuất" HOẶC đề xuấtRevision bằng 3.
`NOT displayName = "proposal" displayName != "proposal"`	`displayName` không bằng với "đề xuất".
`proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED`	`proposalState` có giá trị enum bằng PROPOSED HOẶC BUYER_ rỗng.
`proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED`	`proposalState` có giá trị enum bằng PROPOSED AND BUYER_ hẹp
`dealName = Test Deal`	Biểu thức `INVALID`
`dealName = "Test Deal"`	`dealName` bằng với "Test Deal".
`dealName = (Test Deal)`	`dealName` bằng "Test" (Kiểm thử) và cũng bằng "Deal" (Giao dịch).
`dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"`	`dealName` bằng "Test1" hoặc bằng "Test2".
`dealName:*`	`dealName is not null.`
`dealName:"test" dealName:test`	`dealName` chứa chuỗi con "test".
`dealName:("A B") dealName:"A B"`	`dealName` chứa chuỗi con "A B".
`dealName:(A B) dealName:"A" AND dealName:"B"`	`dealName` chứa chuỗi con "A" và chuỗi con "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` chứa chuỗi con "A" HOẶC "B" VÀ cũng chứa chuỗi con "C"
`dealName:("A B" C) dealName:"A B" AND dealName:"C"`	`dealName` chứa chuỗi con "A B" và cũng chứa chuỗi con "C".
`dealName:("A B" OR C D)`	`dealName` chứa chuỗi con "A B" hoặc "C" và cũng chứa chuỗi con "D".
`dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"`	`dealName` không chứa chuỗi con "A" và cũng chứa chuỗi con "B".
`dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"`	`dealName` không chứa chuỗi con "A" hoặc chứa chuỗi con "B".