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. |
|
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. |
|
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. |
|
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. |
|
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ườngcolors
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ườngcolors
.item.colors:("red" "yellow")
trả về tất cả các mục có cả"red"
và"yellow"
trong trườngcolors
.item.colors:("red" OR "yellow")
trả về tất cả các mục có"red"
hoặc"yellow"
trong trườngcolors
.
item
cũng có một trườngtools
lặp lại. Đây là một đối tượng phức tạp với trường vô hướngshape
. 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 có giá trị số nguyên 93641. |
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 |
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 không bằng với "đề xuất". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState có giá trị enum bằng PROPOSED HOẶC BUYER_ rỗng. |
proposalState = (PROPOSED AND 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 bằng "Test1" hoặc bằng "Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName chứa chuỗi con "test". |
dealName:("A B") |
dealName chứa chuỗi con "A B". |
dealName:(A B) |
dealName chứa chuỗi con "A" và chuỗi con "B". |
dealName:("A" OR "B" AND "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 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) |
dealName không chứa chuỗi con "A" và cũng chứa chuỗi con "B". |
dealName:(NOT "A" OR "B") |
dealName không chứa chuỗi con "A" hoặc chứa chuỗi con "B". |