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 các 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 của bạn.

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 Boolean tổ hợp các phép so sánh:

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

comparison so khớp một trường tài nguyên có 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à lặp lại mớ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 được đặt trong ngoặc đơn
```
value = number| string | "*" | "(" expression ")"
```
Chuỗi có thể đại diện cho 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 là tương đương:

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ụ: như sau đều 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ó khoảng trắng giữa dấu gạch nối (-) và phép so sánh sau đây. Ví dụ: các bộ lọc sau đều giống nhau:

NOT e=f

-e=f

Phép so sánh

Phần này mô tả phép so sánh "name OP value" như sau:

comparison = name OP value

trong đó

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

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

Phía bên phải thường là giá trị vô hướng được chuyển đổi thành giá trị và so sánh với loại dữ liệu đó. Xem các loại Value Literal để biết thêm 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 Boolean được đóng gói tổ hợp các giá trị cố định và/hoặc biểu thức boolean chỉ chứa 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 sẽ được áp dụng cho mỗi giá trị. Ví dụ: các bộ lọc sau đều 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ề hai trường hợp tương đương bộ lọc:

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 kiểu giá trị cố định

Giá trị bên phải của toán tử So sánh có thể được phân loại thành Số và Hằng chuỗi.

Số

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

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

Chuỗi

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

Loại	Định nghĩa	Ví dụ
Boolean	`TRUE` hoặc `FALSE` bằng chữ cái bất kỳ.	`TRUE` `True` `"true"`
Enum	Tên của một giá trị cố định kiểu liệt kê. 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 được mã hoá UTF-8 hoặc 7 bit ASCII. Dấu ngoặc kép được nhúng phải được thoát bằng dấu gạch chéo ngược. Các chuỗi không được trích dẫn có khoảng trắng đượ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	Chuỗi ở định dạng chuẩn ISO8601.	`"2014-10-02T15:01:23.045Z"`

Toán tử so sánh

Dưới đâ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 giá trị Double, Integer, Boolean, Enum và Timestamp loại.

Có nhà cung cấp dịch vụ

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

Chuỗi con

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

Kiểm tra sự tồn tại

Khi bạn sử 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ề mọi thực thể trong đó name không rỗng, bị thiếu hoặc không xác định.

Khi bạn sử dụng toán tử HAS với các 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ụ như isCompleted:true sẽ hoạt động trong cùng cách với isCompleted = true.

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

Bạn có thể dùng toán tử HAS (:) để lọc một tài nguyên API lặp lại , miễn là các điều kiện sau đây là đúng:

Chỉ có một thành phần lặp lại trên đườ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 kiểu 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ó 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ặt hàng có "red" hoặc "yellow" trong trường colors.

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

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

Các trường lồng nhau không được điền sẵn

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

Giá trị mặc định của trường cấp gốc là false. Theo mặc định, các trường lồng nhau không được điền sẵn.

Không trả về giá trị phủ định đối với các đối tượng có trường lồng nhau không được điền sẵn (!=).

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ục sau:

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

Lệnh gọi đến items.list có bộ lọc âm "tools.size != SMALL" trả về như 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 sẽ không trả về đối tượng item3.

Ví dụ

Ví dụ:	Mô tả
`externalDealId = "123456789"`	`externalDealId` có giá trị chuỗi "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` muộn hơn ngày 14/2/2018 11:09:19.378 theo giờ UTC
`displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3`	Chuỗi `displayName` có giá trị giống hệt của "đề xuất" VÀ ĐỀ XUẤT BẢN = 3.
`displayName = "proposal" OR proposalRevision = 3`	`displayName` có giá trị chuỗi là "đề xuất" HOẶC giá trị Đề xuất sửa đổi bằng 3.
`NOT displayName = "proposal" displayName != "proposal"`	`displayName` không bằng "đề xuất".
`proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED`	`proposalState` có giá trị enum bằng PROPOSED HOẶC PURCHASED_personalized.
`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 PURCHASE_ chinh
`dealName = Test Deal`	Biểu thức `INVALID`
`dealName = "Test Deal"`	`dealName` bằng "Giao dịch thử nghiệm".
`dealName = (Test Deal)`	`dealName` bằng "Kiểm thử" và cũng bằng "Deal".
`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 bất kỳ chuỗi con "A" nào 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 bất kỳ chuỗi con "A" nào hoặc chứa chuỗi con "B".