Các phương thức list truy xuất nhiều tài nguyên thuộc một loại tập hợp. Tham số truy vấn filter cho phép bạn đưa ra các tiêu chí mà tài nguyên được truy xuất phải đáp ứng.
Cấu trúc bộ lọc
Giá trị tham số filter là các chuỗi. Các chuỗi này được tạo thành từ một hoặc nhiều tiêu chí. Các tiêu chí được kết hợp bằng toán tử AND hoặc OR.
Một tiêu chí có dạng {field} {operator} {value}. Ví dụ:
entityStatus="ENTITY_STATUS_ACTIVE"
Chuỗi bộ lọc chỉ được có tối đa 500 ký tự. Nếu chuỗi của bạn quá dài:
- Chia logic thành các chuỗi riêng biệt. Thực hiện lệnh gọi
listvới từng chuỗi bộ lọc. Kết hợp các kết quả để tạo thành một danh sách duy nhất. - Xoá tiêu chí khỏi chuỗi bộ lọc. Sử dụng tiêu chí đã xoá để lọc các tài nguyên đã truy xuất cục bộ.
Đặt giá trị cho một tiêu chí trong dấu ngoặc kép.
Đảm bảo rằng các chuỗi bộ lọc của bạn được mã hoá để sử dụng trong một URL khi thực hiện trực tiếp các lệnh gọi API.
Hãy xem phần Tiêu chí kết hợp để biết thêm về cấu trúc chuỗi bộ lọc.
Tiêu chí lọc
Mỗi phương thức danh sách đều hỗ trợ một số tiêu chí lọc nhất định. Nội dung mô tả cho tham số filter của phương thức liệt kê các tiêu chí này. Tiêu chí lọc thường là một tập hợp con của các trường tài nguyên được truy xuất.
Mỗi tiêu chí hỗ trợ một hoặc nhiều toán tử:
| Toán tử so sánh | |
|---|---|
EQUALS (=)
|
Trường này bằng với giá trị đã cho. Ví dụ: |
LESS THAN OR EQUAL TO (<=)
|
Trường nhỏ hơn hoặc bằng giá trị đã cho. Thường dùng để lọc theo ngày hoặc ngày giờ. Ví dụ: |
GREATER THAN OR EQUAL TO (>=)
|
Trường lớn hơn hoặc bằng giá trị đã cho. Thường dùng để lọc theo ngày hoặc ngày giờ. Ví dụ: |
HAS (:)
|
Trường chứa giá trị đã cho. Nếu trường là một chuỗi, thì hàm này sẽ kiểm tra xem giá trị đã cho có phải là một chuỗi con hay không. Nếu trường là một mảng, thì hàm này sẽ kiểm tra mảng để tìm giá trị đã cho. Ví dụ: |
Nếu một tiêu chí không chỉ định toán tử, thì tiêu chí đó chỉ hỗ trợ EQUALS (=).
Một tiêu chí sẽ lưu ý nếu cần có định dạng đặc biệt.
Tiêu chí kết hợp
Kết hợp nhiều tiêu chí để hạn chế thêm phản hồi list.
Kết hợp các tiêu chí bằng toán tử logic AND và OR. Mỗi phương thức list đều chỉ định những phương thức được hỗ trợ. Một số phương thức chỉ hỗ trợ bộ lọc có một tiêu chí.
Hãy cân nhắc những giới hạn này khi sử dụng nhiều tiêu chí:
| Giới hạn và ví dụ | |
|---|---|
AND phải kết hợp các quy tắc hạn chế hoặc nhóm quy tắc hạn chế lọc các trường khác nhau hoặc lọc cùng một trường theo cách khác.
|
updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
|
OR phải kết hợp các quy định hạn chế riêng lẻ để lọc theo cùng một trường.
|
(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
|
OR không thể kết hợp hai nhóm hạn chế. Thay vào đó, hãy sử dụng nhiều yêu cầu list với các giá trị bộ lọc khác nhau.
|
Bạn phải sử dụng 2 chuỗi bộ lọc sau đây trong các yêu cầu riêng biệt và không thể kết hợp bằng toán tử OR:
|
| Dấu ngoặc đơn có thể được ngầm hiểu là để nhóm các điều kiện hạn chế ngay cả khi không có dấu ngoặc đơn. |
Chuỗi bộ lọc updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT" được diễn giải là updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")
|