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