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

บริการส่วนใหญ่ใน API ของ Display & Video 360 จะให้เมธอด 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")