ตัวกรอง

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

ตัวอย่างกรณีการใช้งานที่พบได้ทั่วไปมีดังนี้

ตัวอย่าง	ความหมาย
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 ฟีเจอร์นี้เทียบเท่ากับการค้นหาแบบ universal ใน 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"
• Enums ต้องการการนําเสนอสตริงของ 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

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

ข้อจำกัด

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

สั่งซื้อ

ทรัพยากรส่วนใหญ่รองรับการสั่งซื้อในวิธีการ List โปรดดูเอกสารประกอบของList method เพื่อดูลักษณะการทํางานของทรัพยากรที่แน่นอนและฟิลด์ที่รองรับสำหรับการสั่งซื้อ

ไวยากรณ์สำหรับช่อง orderBy คือรายการชื่อช่องที่คั่นด้วยคอมมา เช่น "foo,bar"

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

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

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