บริการส่วนใหญ่ใน 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 (=)
|
ค่าในช่องทรัพยากรเท่ากับค่าที่ระบุ
เช่น |
|
LESS THAN OR EQUAL TO (<=)
|
ค่าในช่องทรัพยากรน้อยกว่าหรือเท่ากับค่าที่กำหนด มักใช้เมื่อเปรียบเทียบวันที่หรือเวลา
เช่น |
|
GREATER THAN OR EQUAL TO (>=)
|
ค่าในช่องทรัพยากรมากกว่าหรือเท่ากับค่าที่กำหนด มักใช้เมื่อเปรียบเทียบวันที่หรือเวลา
เช่น |
|
HAS (:)
|
ค่าในช่องทรัพยากรมีค่าที่ระบุ หากช่องทรัพยากรเป็นสตริง ช่องดังกล่าวจะตรวจสอบว่าค่าที่ระบุเป็นสตริงย่อยที่มีอยู่หรือไม่ หากช่องทรัพยากรเป็นอาร์เรย์ ระบบจะตรวจสอบว่าอาร์เรย์มีค่าที่ระบุหรือไม่
เช่น |
หากไม่ได้ระบุโอเปอเรเตอร์สำหรับช่องในคำอธิบายของพารามิเตอร์ คุณจะใช้ได้เฉพาะโอเปอเรเตอร์ 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")