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. 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ụ: entityStatus="ENTITY_STATUS_ACTIVE"
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ụ: updateTime<="2023-04-01T12:00:00Z"
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ụ: updateTime>="2023-03-01T12:00:00Z"
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ụ: lineItemIds:"1234"

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ầu LIST với các giá trị bộ lọc khác nhau. Ví dụ: hãy sử dụng các yêu cầu LIST 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")