กรองคำตอบในรายการ

บริการส่วนใหญ่ใน Display & Video 360 API มีLISTวิธีการดึงข้อมูลทรัพยากรจํานวนมาก โดยปกติแล้วLISTเมธอดเหล่านี้จะรองรับการกรองผลลัพธ์ผ่านพารามิเตอร์การค้นหา filter ใช้พารามิเตอร์นี้เพื่อเพิ่มประสิทธิภาพการใช้ API โดยดึงข้อมูลเฉพาะสิ่งที่ต้องการเท่านั้น

คู่มือนี้จะแสดงวิธีใช้พารามิเตอร์ filter อย่างมีประสิทธิภาพ

โครงสร้างตัวกรอง

ค่าพารามิเตอร์ filter คือสตริงที่ประกอบด้วยข้อจํากัดอย่างน้อย 1 ข้อ ซึ่งสามารถรวมเข้ากับโอเปอเรเตอร์ AND หรือ OR และจัดกลุ่มโดยใช้วงเล็บ

ข้อจํากัดมีรูปแบบเป็น {field} {operator} {value} ตัวอย่าง

entityStatus="ENTITY_STATUS_ACTIVE"

ความยาวของสตริงตัวกรองต้องไม่เกิน 500 อักขระ หากสตริงตัวกรองมีความยาวเกิน 500 อักขระ ให้ทําอย่างใดอย่างหนึ่งต่อไปนี้

  • แยกตรรกะออกเป็นสตริงตัวกรองหลายรายการ และดึงข้อมูลโดยใช้คำขอ LIST แยกต่างหาก
  • นำตรรกะบางส่วนออกจากสตริงตัวกรอง และใช้เพื่อกรองทรัพยากรที่ดึงข้อมูลไว้ในพื้นที่

ใส่ค่าข้อจํากัดในเครื่องหมายคําพูดเพื่อให้ระบบใช้ตรรกะอย่างถูกต้อง

เข้ารหัสสตริงตัวกรองเป็น URL หากคุณเรียกใช้ LIST โดยตรงโดยไม่ใช้ไลบรารีไคลเอ็นต์

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการจัดรูปแบบการค้นหาได้ที่ตรรกะระหว่างข้อจํากัด

ฟิลด์ที่กรองได้

ช่องที่กรองได้ของวิธีการ LIST แต่ละรายการจะแสดงอยู่ในคำอธิบายพารามิเตอร์ filter ของวิธีการ ในกรณีส่วนใหญ่ คุณจะกรองข้อมูลย่อยของช่องมาตรฐานของทรัพยากรได้ ในบางกรณีที่พบไม่บ่อยนัก จะมีช่องเพิ่มเติมที่คุณใช้ได้สําหรับการกรองเท่านั้น

แต่ละช่องในคำอธิบายของพารามิเตอร์รองรับโอเปอเรเตอร์แบบเปรียบเทียบต่อไปนี้อย่างน้อย 1 รายการ

โอเปอเรเตอร์ที่เปรียบเทียบได้
EQUALS (=) ค่าในช่องทรัพยากรเท่ากับค่าที่ระบุ

ตัวอย่าง: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) ค่าในช่องทรัพยากรน้อยกว่าหรือเท่ากับค่าที่ระบุ มักใช้เมื่อเปรียบเทียบวันที่หรือวันที่และเวลา

ตัวอย่าง: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) ค่าในช่องทรัพยากรมากกว่าหรือเท่ากับค่าที่ระบุ มักใช้เมื่อเปรียบเทียบวันที่หรือวันที่และเวลา

ตัวอย่าง: updateTime>="2023-03-01T12:00:00Z"
HAS (:) ค่าในช่องทรัพยากรมีค่าที่ระบุ หากช่องทรัพยากรเป็นสตริง ระบบจะตรวจสอบว่าค่าที่ระบุคือสตริงย่อยที่มีอยู่หรือไม่ หากช่องแหล่งข้อมูลเป็นอาร์เรย์ ระบบจะตรวจสอบว่าอาร์เรย์มีค่าที่ระบุหรือไม่

ตัวอย่าง: lineItemIds:"1234"

หากไม่ได้ระบุโอเปอเรเตอร์สำหรับช่องในคำอธิบายของพารามิเตอร์ คุณจะใช้ได้เฉพาะโอเปอเรเตอร์ EQUALS (=) บางช่องรองรับโอเปอเรเตอร์หลายรายการ

ฟิลด์ที่กรองได้บางฟิลด์ เช่น ฟิลด์สำหรับวันที่และเวลา กำหนดให้ค่าที่เปรียบเทียบได้ต้องเป็นไปตามรูปแบบที่เฉพาะเจาะจง รูปแบบจะระบุไว้ข้างช่องในคำอธิบายพารามิเตอร์ filter

ตรรกะระหว่างข้อจํากัด

คุณสามารถรวมข้อจำกัดหลายรายการเข้าด้วยกันเพื่อจำกัดหรือขยายการตอบกลับจากคำขอLIST

โดยทั่วไปแล้ว คุณสามารถรวมข้อจํากัดหลายรายการเข้าด้วยกันได้โดยใช้ตัวดำเนินการตรรกะ AND และ OR วิธีการ LIST แต่ละวิธีจะระบุโอเปอเรเตอร์ที่รองรับ บางวิธีรองรับการใช้ข้อจํากัดรายการเดียวในพารามิเตอร์ filter เท่านั้น

โปรดคำนึงถึงข้อจำกัดต่อไปนี้เมื่อสร้างสตริงตัวกรองด้วยโอเปอเรเตอร์ตรรกะ AND หรือ OR

  • AND ต้องอยู่ระหว่างข้อจํากัดหรือกลุ่มข้อจํากัดที่กรองฟิลด์ต่างๆ หรือกรองฟิลด์เดียวกันในลักษณะที่แตกต่างกัน ตัวอย่างมีดังนี้
    • 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")
  • OR ต้องอยู่ระหว่างข้อจำกัดแต่ละรายการที่กรองตามช่องเดียวกัน ตัวอย่างมีดังนี้
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • คุณใช้ OR เพื่อรวมข้อจำกัด 2 กลุ่มเข้าด้วยกันไม่ได้ ให้ใช้คำขอ LIST หลายรายการที่มีค่าตัวกรองต่างกันแทน ตัวอย่างเช่น ให้ใช้คำขอ LIST แยกต่างหากต่อไปนี้

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

    อย่าใช้โอเปอเรเตอร์ OR เพื่อรวมรายการต่อไปนี้

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

  • ระบบอาจใช้วงเล็บโดยนัยหากคุณไม่ได้ใช้วงเล็บเพื่อจัดกลุ่มข้อจํากัดในสตริงตัวกรอง เช่น สตริงตัวกรองต่อไปนี้

    updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

    ระบบตีความเป็น

    updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")