Lọc câu trả lời cho danh sách

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. Sử dụng tham số này để tối ưu hoá mức sử dụng API bằng cách chỉ truy xuất những gì bạn cần.

Hướng dẫn này cho biết cách sử dụng thông số filter một cách hiệu quả.

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 quy tắc hạn chế có thể được kết hợp với toán tử AND hoặc OR và được nhóm bằng dấu ngoặc đơn.

Các quy định hạn chế có dạng {field} {operator} {value}. Dưới đây là một ví dụ:

entityStatus="ENTITY_STATUS_ACTIVE"

Chuỗi bộ lọc không được dài quá 500 ký tự. Nếu chuỗi bộ lọc 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 tài nguyên bằ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 chuỗi này để lọc tài nguyên được truy xuất cục bộ.

Gói các giá trị hạn chế trong dấu ngoặc kép để đảm bảo logic được áp dụng đúng cách.

Mã hoá URL cho chuỗi bộ lọc nếu bạn đang thực hiện trực tiếp lệnh gọi LIST mà không sử dụng thư viện ứng dụng.

Hãy xem phần Logic giữa các quy định hạn chế để biết thêm thông tin chi tiết về cách định dạng truy vấn.

Các 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 các trường hợp, bạn có thể lọc theo một tập hợp con của các trường tiêu chuẩn của tài nguyên. Trong một số ít trường hợp, có các trường bổ sung mà bạn chỉ có thể sử dụng để lọc.

Mỗi trường trong nội dung mô tả của tham số hỗ trợ ít nhất một trong các toán tử có thể so sánh sau:

Toán tử tương đương
EQUALS (=) Giá trị trường tài nguyên bằng giá trị đã cho.

Ví dụ: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) Giá trị trường tài nguyên nhỏ hơn hoặc bằng giá trị đã cho. Thường dùng khi so sánh ngày hoặc ngày giờ.

Ví dụ: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) Giá trị 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 ngày hoặc ngày giờ.

Ví dụ: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Giá trị 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ì trường này sẽ kiểm tra xem giá trị đã cho có phải là một chuỗi con hiện có hay không. Nếu trường tài nguyên là một mảng, thì trường này sẽ kiểm tra xem mảng có chứa giá trị đã cho hay không.

Ví dụ: lineItemIds:"1234"

Nếu không chỉ định toán tử nào cho trường trong phần mô tả của tham số, 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ư trường cho ngày và giờ, yêu cầu giá trị có thể so sánh phải tuân 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 quy định hạn chế

Bạn có thể kết hợp nhiều quy định hạn chế để thu hẹp hoặc mở rộng phản hồi từ yêu cầu LIST.

Thông thường, bạn có thể kết hợp nhiều quy tắc hạn chế với toán tử logic AND và OR. Mỗi phương thức LIST chỉ định toán tử mà phương thức đó hỗ trợ. Một số phương thức chỉ hỗ trợ sử dụng một quy tắc hạn chế trong tham số filter.

Hãy cân nhắc các hạn chế sau đây khi tạo 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 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 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 quy tắc hạn chế riêng lẻ lọc theo cùng một trường. Sau đây là một ví dụ:
    • (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ế. 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. Ví dụ: sử dụng các yêu cầu LIST riêng biệt sau:

    • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
    • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

    Không sử dụng toán tử OR để kết hợp các thành phần này:

    (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  • Bạn có thể ngầm hiểu dấu ngoặc đơn nếu không sử dụng dấu ngoặc đơn để nhóm các quy định 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 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")