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

Hầu hết các dịch vụ trong Mạng Hiển thị Video 360 API cung cấp phương thức LIST để truy xuất hàng loạt của chúng tôi. 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. Chỉ dùng tham số này để tối ưu hoá mức sử dụng API của bạn truy xuất thông tin bạn cần.

Hướng dẫn này sẽ cho bạn biết cách sử dụng hiệu quả tham 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 quy tắc 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 cách sử dụ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"

Độ dài chuỗi bộ lọc không thể 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 thực hiện một trong những thao tác sau:

  • Chia logic thành nhiều chuỗi bộ lọc và truy xuất tài nguyên bằng cách sử dụng riêng các yêu cầu LIST.
  • Xoá một số logic khỏi chuỗi bộ lọc và sử dụng logic đó để 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 áp dụng logic đúng cách.

Mã hoá URL cho 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 thông qua thư viện ứng dụng.

Xem bài viết Logic giữa các hạn chế để biết thêm thông tin chi tiết về định dạng truy vấn của bạ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 filter của mỗi phương thức phần mô tả tham số. Trong hầu hết các trường hợp, bạn có thể lọc một tập hợp con trường chuẩn. Trong một số ít trường hợp, bạn có thể sử dụng các trường bổ sung chỉ để lọc.

Mỗi trường trong phần mô tả của tham số hỗ trợ ít nhất một trong các trường sau toán tử tương đương:

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 một 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 một 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 thì chuỗi này 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, trường này sẽ kiểm tra xem mảng đó có chứa các giá trị.

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ố, 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 được, chẳng hạn như các trường cho ngày và giờ, yêu cầu giá trị tương đương để tuân theo một định dạng cụ thể. Định dạng được chỉ định bên cạnh 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 câu trả lời từ Yêu cầu LIST.

Thường thì bạn có thể kết hợp nhiều quy định hạn chế với AND và OR toán tử logic. Mỗi phương thức LIST 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 hạn chế duy nhất trong tham số filter.

Hãy xem xét các hạn chế sau đây khi tạo chuỗi bộ lọc bằng AND hoặc toán tử logic OR:

  • AND phải được sử dụng giữa các hạn chế hoặc nhóm hạn chế mà lọc các trường khác nhau hoặc lọc cùng một trường theo cách khác. Sau đâ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 những quy định hạn chế riêng lẻ lọc theo cùng một quy tắc hạn chế . 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 hạn chế. Sử dụng nhiều LIST yêu cầu có giá trị bộ lọc khác. Ví dụ: sử dụng sau đây là các yêu cầu LIST riêng biệt:

    • (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 toán tử này:

    (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 quy tắ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")