ฟิลเตอร์

Ad Manager API รองรับการกรองในวิธีการ List รูปแบบสตริงตัวกรองจะกําหนดอย่างเป็นทางการในไวยากรณ์ EBNF

ลองดูตัวอย่าง Use Case ที่พบบ่อยเพื่อเริ่มต้นใช้งาน

ตัวอย่าง	ความหมาย
orders.updateTime > "2024-01-01T00:00:00-5:00"	แสดงคำสั่งซื้อที่มี updateTime หลังวันที่ 1 มกราคม 2024 ตามเขตเวลามาตรฐานตะวันออก
lineItems.targeting.geoTargeting.targetedGeoIds:2840	แสดงรายการรายการโฆษณาที่มีการกำหนดเป้าหมายตามภูมิศาสตร์ที่มีสหรัฐอเมริกา (รหัสเป้าหมายทางภูมิศาสตร์ 2480)
lineItems.displayName = "*_interstitial"	แสดงรายการโฆษณาที่มีชื่อที่แสดงซึ่งลงท้ายด้วยสตริง _interstitial
orders.displayName = "*video*"	แสดงคำสั่งซื้อที่มีชื่อที่แสดงซึ่งมีสตริง video
displayName:"video"	แสดงรายการคำสั่งซื้อที่มีชื่อที่แสดงซึ่งมีสตริง video (ไวยากรณ์ทางเลือก)

เคล็ดลับ: ตัวกรองต้องเข้ารหัส URL สําหรับคําขอ GET เช่น
สตริงตัวกรอง: orders.updateTime > "2024-01-01T00:00:00-5:00"
URL ที่เข้ารหัส: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22
ไลบรารีของไคลเอ็นต์จะจัดการเรื่องนี้โดยอัตโนมัติ

ลิเทอรัล

ค่าที่เป็นตัวอักษรล้วน (เช่น 42, Hugo) คือค่าที่จะจับคู่ ข้อความที่ปรากฏขึ้นเพียงอย่างเดียวจะจับคู่แบบไม่ตรงทั้งหมดกับช่องที่รองรับทั้งหมดในทรัพยากร แหล่งข้อมูลจะระบุฟิลด์ที่ระบบจะพิจารณาจับคู่ในวิธีการ list ฟีเจอร์นี้เทียบเท่ากับการค้นหาอเนกประสงค์ใน UI ของ Ad Manager แต่กําหนดขอบเขตไว้สำหรับทรัพยากรประเภทเดียว

ควรรวมลิเทอรัลสตริงที่มีการเว้นวรรคไว้ในเครื่องหมายคำพูดคู่ (เช่น "Foo bar") ไม่สามารถใช้เครื่องหมายคำพูดเดี่ยวเพื่อตัดลิเทอรัลของสตริงได้

โอเปอเรเตอร์ทางตรรกะ

Ad Manager API รองรับโอเปอเรเตอร์ไบนารี AND และ OR

ข้อควรระวัง: โอเปอเรเตอร์เหล่านี้คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ระบบจะถือว่าค่าคงที่ and และ or เป็นค่าคงที่

โอเปอเรเตอร์	ตัวอย่าง	ความหมาย
AND	a AND b	เป็นจริงหาก a และ b เป็นจริง
OR	a OR b OR c	จริงหาก a, b, c เป็นจริง

หมายเหตุ: โอเปอเรเตอร์ OR มีความสำคัญมากกว่า AND เพื่อให้ตรงกับรูปแบบการพูดทั่วไป ซึ่งแตกต่างจากที่พบในภาษาโปรแกรมส่วนใหญ่ นิพจน์ a AND b OR c จะประเมินเป็น a AND (b OR c) เมื่อเป็นไปได้ ให้ใช้วงเล็บอย่างชัดแจ้งเพื่อหลีกเลี่ยงความสับสน

โอเปอเรเตอร์การปฏิเสธ

Ad Manager API มีโอเปอเรเตอร์รวม NOT และ - ซึ่งใช้แทนกันได้

โอเปอเรเตอร์	ตัวอย่าง	ความหมาย
NOT	NOT a	จริงหาก a ไม่ใช่จริง
-	-a	เป็นจริงหาก a ไม่เป็นความจริง

โอเปอเรเตอร์การเปรียบเทียบ

Ad Manager API รองรับโอเปอเรเตอร์การเปรียบเทียบแบบไบนารี =, !=, <, >, <= และ >= สำหรับช่องสตริง ตัวเลข การประทับเวลา และระยะเวลา

โอเปอเรเตอร์	ตัวอย่าง	ความหมาย
=	a = true	จริงหาก a เป็นจริง
!=	a != 42	จริง เว้นแต่ a จะเท่ากับ 42
<	a < 42	จริงหาก a เป็นค่าตัวเลขที่น้อยกว่า 42
>	a > "foo"	จริงหาก a มีลําดับตามคําศัพท์หลัง "foo"
<=	a <= "foo"	เป็นจริงหาก a เป็น "foo" หรือคำศัพท์ก่อนหน้า
>=	a >= 42	จริงหาก a เป็นค่าตัวเลขที่มากกว่าหรือเท่ากับ 42

หมายเหตุ: ชื่อช่องต้องปรากฏที่ด้านซ้ายของโอเปอเรเตอร์เปรียบเทียบ ซึ่งต่างจากภาษาโปรแกรมส่วนใหญ่ ด้านขวามือจะยอมรับเฉพาะอักขระตามตัวอักษรและโอเปอเรเตอร์เชิงตรรกะเท่านั้น

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

• สตริงต้องใช้เครื่องหมายคำพูดคู่ ตัวอย่าง: "Foo bar"
• ประเภทข้อมูล Enum ต้องการการนําเสนอสตริงของ Enum (คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่)
• บูลีนต้องการค่าลิเทอรัล true และ false
• ตัวเลขควรเป็นการแสดงจำนวนเต็มหรือทศนิยมมาตรฐาน สำหรับตัวเลขทศนิยม ระบบจะรองรับเลขชี้กำลัง ตัวอย่าง: 2.997e9
• ระยะเวลาควรเป็นตัวเลขตามด้วยส่วนต่อท้าย s (สำหรับวินาที) ตัวอย่าง: "20s", "1.2s"
• การประทับเวลาต้องการสตริงรูปแบบ RFC-3339 ตัวอย่างเช่น "2012-04-21T11:30:00-04:00" ระบบรองรับความต่างเวลา UTC

ข้อควรระวัง: ตัวระบุ true, false และ null จะมีความหมายโดยเนื้อแท้ก็ต่อเมื่อใช้ในบริบทของการอ้างอิงช่องที่มีประเภท

สัญลักษณ์แทน

เมื่อเปรียบเทียบสตริงเพื่อหาค่าที่เท่ากัน Ad Manager API จะรองรับไวลด์การ์ดโดยใช้อักขระ *

ตัวอย่าง	ความหมาย
a = "*.foo"	จริงหาก a ลงท้ายด้วย ".foo"

โอเปอเรเตอร์การท่องเว็บ

Ad Manager API รองรับโอเปอเรเตอร์ . ซึ่งระบุการท่องผ่านข้อความ แผนที่ หรือโครงสร้าง

ตัวอย่าง	ความหมาย
a.b = true	จริงหาก a มีช่องบูลีน b ที่จริง
a.b > 42	จริงหาก a มีฟิลด์ b ที่เป็นตัวเลขมากกว่า 42
a.b.c = "foo"	จริงหาก a.b มีฟิลด์สตริง c เป็น "foo"

การเรียกใช้นี้จะเขียนโดยใช้ชื่อช่องจากแหล่งข้อมูล บริการแต่ละรายการอาจระบุชุดย่อยของฟิลด์ที่รองรับการข้ามผ่าน

สำคัญ: คุณใช้โอเปอเรเตอร์ . เพื่อไปยังส่วนต่างๆ ของฟิลด์หรือลิสต์ที่ซ้ำกันไม่ได้ ยกเว้นการใช้งานที่เฉพาะเจาะจงกับโอเปอเรเตอร์ :

มีโอเปอเรเตอร์

Ad Manager API รองรับโอเปอเรเตอร์ : ซึ่งหมายถึง "มี" โดยจะใช้ได้กับคอลเล็กชัน (ฟิลด์หรือแผนที่ซ้ำ) ข้อความ และสตริง โดยจะทำงานแตกต่างกันเล็กน้อยในแต่ละกรณี

การค้นหาฟิลด์สตริงเพื่อดูว่าสตริงมีสตริงย่อยที่ตรงกันหรือไม่

ตัวอย่าง	ความหมาย
r.displayName:"_250x250"	จริงหากช่องสตริง r.displayName มีสตริงย่อย _250x250

การค้นหาฟิลด์ที่ซ้ำเพื่อดูว่าโครงสร้างที่ซ้ำกันมีองค์ประกอบที่ตรงกันหรือไม่

ตัวอย่าง	ความหมาย
r:42	จริงหาก r มี 42
r.foo:42	จริงหาก r มีองค์ประกอบ e ดังที่ e.foo = 42

สำคัญ: ตัวกรองจะค้นหาองค์ประกอบที่เฉพาะเจาะจงในช่องที่ซ้ำกันเพื่อหาค่าไม่ได้ ตัวอย่างเช่น e.0.foo = 42 และ e[0].foo = 42 เป็นตัวกรองที่ไม่ถูกต้อง

แผนที่ โครงสร้าง และข้อความสามารถค้นหาว่ามีช่องในแผนที่หรือค่าที่เฉพาะเจาะจงหรือไม่ โดยทำดังนี้

ตัวอย่าง	ความหมาย
m:foo	จริงหาก m มีคีย์ "foo"
m.foo:*	จริงหาก m มีคีย์ "foo"
m.foo:42	เป็นจริงหาก m.foo คือ 42

เมื่อเรียกดูข้อความ ระบบจะถือว่ามีฟิลด์เฉพาะในกรณีที่มีค่าที่ไม่ใช่ค่าเริ่มต้นเท่านั้น

ข้อจำกัด

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

สั่งซื้อ

Ad Manager API รองรับการสั่งซื้อด้วยเมธอด List รูปแบบคำสั่งสำหรับช่อง orderBy คือรายการชื่อช่องที่คั่นด้วยคอมมา ตัวอย่างเช่น "foo,bar"

ลำดับการจัดเรียงเริ่มต้นคือจากน้อยไปมาก หากต้องการระบุลําดับจากมากไปน้อยสําหรับช่อง ให้ใส่ส่วนต่อท้าย " desc" ต่อท้าย เช่น "foo desc, bar"

ระบบจะไม่สนใจอักขระเว้นวรรคที่ซ้ำกันในไวยากรณ์ ค่า "foo, bar desc", " foo , bar desc " และ "foo,bar desc" ทั้งหมดเทียบเท่ากัน

ช่องย่อยจะระบุด้วยโอเปอเรเตอร์ Traversal เช่น foo.bar หรือ address.street