Hầu hết các dịch vụ trong API Display & Video 360 đều cung cấp phương thức LIST
để truy xuất hàng loạt tài nguyên. Các phương thức LIST
này thường hỗ trợ lọc kết quả thông qua tham số truy vấn filter
. Hãy sử dụng tham số này để tối ưu hoá việc sử dụng API bằng cách chỉ truy xuất những dữ liệu bạn cần.
Hướng dẫn này cho biết cách sử dụng hiệu quả thông số filter
.
Cấu trúc bộ lọc
Giá trị tham số filter
là một chuỗi, bao gồm một hoặc nhiều hạn chế có thể kết hợp với các toán tử AND
hoặc OR
và được nhóm lại bằng dấu ngoặc đơn.
Các quy định hạn chế có dạng {field} {operator} {value}
. Ví dụ như sau:
entityStatus="ENTITY_STATUS_ACTIVE"
Độ dài chuỗi bộ lọc không được vượt quá 500 ký tự. Nếu chuỗi bộ lọc của bạn vượt quá 500 ký tự, hãy làm theo một trong những cách sau:
- Tách logic thành nhiều chuỗi bộ lọc và truy xuất các tài nguyên bằng cách sử dụng các yêu cầu
LIST
riêng biệt. - Xoá một số logic khỏi chuỗi bộ lọc và sử dụng logic đó để lọc cục bộ các tài nguyên được truy xuất.
Gói giá trị hạn chế trong dấu ngoặc kép để đảm bảo áp dụng logic chính xác.
Hãy mã hoá URL các chuỗi bộ lọc nếu bạn đang thực hiện lệnh gọi LIST
trực tiếp mà không cần sử dụng thư viện ứng dụng.
Hãy xem bài viết Logic giữa các hạn chế để biết thêm thông tin chi tiết về cách định dạng truy vấn.
Những trường có thể lọc
Các trường có thể lọc của mỗi phương thức LIST
được liệt kê trong phần mô tả tham số filter
của phương thức đó. Trong hầu hết trường hợp, bạn có thể lọc một nhóm nhỏ các trường chuẩn của tài nguyên. Trong một số ít trường hợp, bạn chỉ có thể sử dụng các trường bổ sung để lọc.
Mỗi trường trong phần mô tả của thông số hỗ trợ ít nhất một trong các toán tử so sánh sau đây:
Toán tử tương đương | ||
---|---|---|
EQUALS (=)
|
Giá trị của trường tài nguyên bằng giá trị đã cho.
Ví dụ: |
|
LESS THAN OR EQUAL TO (<=)
|
Giá trị của trường tài nguyên nhỏ hơn hoặc bằng giá trị đã cho. Thường dùng khi so sánh một ngày hoặc ngày giờ.
Ví dụ: |
|
GREATER THAN OR EQUAL TO (>=)
|
Giá trị của trường tài nguyên lớn hơn hoặc bằng giá trị đã cho. Thường dùng khi so sánh một ngày hoặc ngày giờ.
Ví dụ: |
|
HAS (:)
|
Giá trị của trường tài nguyên chứa giá trị đã cho. Nếu trường tài nguyên là một chuỗi, thì hệ thống sẽ kiểm tra xem giá trị đã cho có phải là chuỗi con hiện có hay không. Nếu trường tài nguyên là một mảng, công cụ này sẽ kiểm tra xem mảng đó có chứa giá trị đã cho hay không.
Ví dụ: |
Nếu không có toán tử nào được chỉ định cho trường trong phần mô tả của tham số, thì bạn chỉ có thể sử dụng toán tử EQUALS (=)
. Một số trường hỗ trợ nhiều toán tử.
Một số trường có thể lọc, chẳng hạn như các trường cho ngày và giờ, yêu cầu giá trị so sánh phải theo một định dạng cụ thể. Định dạng được chỉ định bên cạnh trường trong phần mô tả tham số filter
.
Logic giữa các hạn chế
Bạn có thể kết hợp nhiều hạn chế để thu hẹp hoặc mở rộng phản hồi từ yêu cầu LIST
của mình.
Thường thì bạn có thể kết hợp nhiều hạn chế bằng các toán tử logic AND
và OR
. Mỗi phương thức LIST
sẽ chỉ định những toán tử mà phương thức đó hỗ trợ.
Một số phương thức chỉ hỗ trợ việc sử dụng một quy định hạn chế duy nhất trong tham số filter
.
Hãy xem xét các hạn chế sau khi xây dựng chuỗi bộ lọc bằng toán tử logic AND
hoặc OR
:
- Bạn phải sử dụng
AND
giữa các hạn chế hoặc nhóm quy định 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 nhau. Dưới đây là một số ví dụ:updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
- Bạn phải sử dụng
OR
giữa các hạn chế riêng lẻ lọc theo cùng một trường. Ví dụ như sau:(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
Bạn không thể sử dụng
OR
để kết hợp hai nhóm quy định hạn chế. Hãy sử dụng nhiều yêu cầuLIST
với các giá trị bộ lọc khác nhau. Ví dụ: hãy sử dụng các yêu cầuLIST
riêng biệt sau đây:(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
(lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
Đừng sử dụng toán tử
OR
để kết hợp chúng:(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
Dấu ngoặc đơn có thể được ngụ ý nếu bạn không sử dụng chúng để nhóm các hạn chế trong một chuỗi bộ lọc. Ví dụ: chuỗi bộ lọc sau:
updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"
được hiểu là:
updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")