ฟิลเตอร์

REST API ของ Ad Manager รองรับการกรองในเมธอด 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 ฟีเจอร์นี้คล้ายกับการค้นหาอเนกประสงค์ใน UI ของ Ad Manager แต่จำกัดขอบเขตอยู่ที่ทรัพยากรประเภทเดียว

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

โอเปอเรเตอร์เชิงตรรกะ

REST API ของ Ad Manager รองรับโอเปอเรเตอร์ไบนารี 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) หากทำได้ ให้ใช้วงเล็บเหลี่ยมที่ชัดเจนเพื่อไม่ให้เกิดความสับสน

โอเปอเรเตอร์นิเสธ

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

ผู้ประกอบธุรกิจ	ตัวอย่าง	ความหมาย
NOT	NOT a	เป็นจริงหาก a ไม่เป็นความจริง
-	-a	เป็นจริงหาก a ไม่เป็นความจริง

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

Ad Manager REST 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 REST API จะรองรับไวลด์การ์ดโดยใช้อักขระ *

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

โอเปอเรเตอร์การส่งผ่าน

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

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

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

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

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

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

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

ตัวอย่าง	ความหมาย
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

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

ข้อจำกัด

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

สั่งซื้อ

REST API ของ Ad Manager รองรับการจัดลำดับในเมธอด List ไวยากรณ์สำหรับช่อง orderBy คือรายการชื่อช่องที่คั่นด้วยคอมมา ตัวอย่างเช่น "foo,bar"

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

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

ฟิลด์ย่อยจะระบุด้วยโอเปอเรเตอร์การข้ามผ่าน ตัวอย่างเช่น foo.bar หรือ address.street