מסננים

ב-Ad Manager API יש תמיכה בסינון בשיטות List. התחביר של מחרוזת המסנן מוגדר באופן רשמי בתחביר EBNF.

כדי להתחיל, ריכזנו כאן כמה דוגמאות לתרחישי שימוש נפוצים.

דוגמה	משמעות
orders.updateTime > "2024-01-01T00:00:00-5:00"	הצגת הזמנות עם הערך updateTime אחרי 1 בינואר 2024 באזור הזמן החוף המזרחי (EST)
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. התכונה הזו דומה לחיפוש אוניברסלי בממשק המשתמש של Ad Manager, אבל היא מוגבלת לסוג משאב אחד.

יש לתחום מחרוזות לוגיות שמכילות רווחים במירכאות כפולות (לדוגמה: "Foo bar"). אי אפשר להשתמש במירכאות יחידות כדי לתחום מחרוזות לוגיות.

אופרטורים לוגיים

ב-Ad Manager API יש תמיכה באופרטורים הבינאריים AND ו-OR.

זהירות: האופרטורים האלה תלויים אותיות רישיות. המשתנים המילוליים and ו-or נחשבים כמשתנים מילוליים.

מפעיל	דוגמה	משמעות
AND	a AND b	הפונקציה מחזירה את הערך True אם הערכים של a ו-b הם True.
OR	a OR b OR c	הפונקציה מחזירה את הערך True אם אחד מהערכים a,‏ b או c הוא True.

הערה: כדי להתאים לדפוסי דיבור נפוצים, אופרטור OR מקבל עדיפות גבוהה יותר מ-AND, בניגוד למה שקורה ברוב שפות התכנות. הערך של הביטוי a AND b OR c הוא a AND (b OR c). כשהדבר אפשרי, כדאי להשתמש בסוגריים מפורשים כדי למנוע בלבול.

אופרטורים של הכחשה

ב-Ad Manager API יש את האופרטורים החד-ערכיים NOT ו--. אפשר להשתמש בהם באופן חלופי.

מפעיל	דוגמה	משמעות
NOT	NOT a	הפונקציה מחזירה את הערך True אם הערך של a לא נכון.
-	-a	הפונקציה מחזירה את הערך True אם הערך של a לא נכון.

אופרטורים להשוואה

ב-Ad Manager API יש תמיכה באופרטור השוואה בינארי =, !=, <, >, <= ו->= בשדות של מחרוזות, ערכים מספריים, חותמות זמן ומשכים.

מפעיל	דוגמה	משמעות
=	a = true	הפונקציה מחזירה את הערך True אם הערך של a הוא True.
!=	a != 42	הערך יהיה True אלא אם הערך של a שווה ל-42.
<	a < 42	הפונקציה מחזירה את הערך True אם הערך של a הוא מספרי וקטן מ-42.
>	a > "foo"	הפונקציה מחזירה את הערך True אם a מופיע אחרי foo בסדר לקסיקלי.
<=	a <= "foo"	הפונקציה מחזירה את הערך True אם a הוא "foo" או מופיע לפניו מבחינה לקסיקלית.
>=	a >= 42	הערך מוגדר כ-True אם a הוא ערך מספרי של 42 ומעלה.

הערה: בשונה מרוב שפות התכנות, שמות השדות חייבים להופיע בצד ימין של אופרטור ההשוואה. בצד ימין אפשר להשתמש רק בערכים לינאריים ובאופרטורים לוגיים.

מכיוון שמסננים מתקבלים כמחרוזות שאילתות, מתבצעת המרה של הסוג כדי לתרגם את המחרוזת לערך המתאים עם סוג מוגדר:

• מחרוזות צריכות להיות מוקפות במירכאות כפולות. דוגמה: "Foo bar"
• ב-enums צריך לציין את ייצוג המחרוזת של ה-enum (תלוי אותיות רישיות).
• בערכים בוליאניים צריך להשתמש בערכי הליבה true ו-false.
• המספרים צריכים להיות מיוצגים כמספרים שלמים או כמספרים בנקודה צפה (float). ב-floats יש תמיכה בחזקות. דוגמה: 2.997e9
• משכי זמן צריכים להיות מיוצגים במספר ואחריו הסיומת s (לצורך ציון שניות). דוגמאות: "20s", ‏ "1.2s".
• חותמות זמן צריכות להיות בפורמט של מחרוזת RFC-3339. דוגמה: "2012-04-21T11:30:00-04:00". יש תמיכה בסטיות ל-UTC.

זהירות: המזהים true,‏ false ו-null נושאים משמעות מהותית רק כשמשתמשים בהם בהקשר של הפניה לשדה מוגדר.

תווים כלליים לחיפוש

כשמשווים בין מחרוזות כדי לבדוק אם הן זהות, ב-Ad Manager API יש תמיכה בתווים כלליים לחיפוש באמצעות התו *.

דוגמה	משמעות
a = "*.foo"	הפונקציה מחזירה את הערך True אם a מסתיימת ב-"‎.foo".

אופרטור טרנסלוציה

ב-Ad Manager API יש תמיכה באופרטור ., שמציין סריקה של הודעה, מפה או מבנה.

דוגמה	משמעות
a.b = true	הפונקציה מחזירה את הערך True אם לשדה a יש שדה בוליאני b שהוא true.
a.b > 42	הפונקציה מחזירה את הערך True אם ל-a יש שדה b מספרי שגדול מ-42.
a.b.c = "foo"	הפונקציה מחזירה את הערך True אם ל-a.b יש שדה מחרוזת c שהערך שלו הוא 'foo'.

הטרaversal נכתב באמצעות שמות השדות מהמשאב. שירותים ספציפיים יכולים לציין קבוצת משנה של שדות שנתמכים לצורך סריקה.

חשוב: אי אפשר להשתמש באופרטור . כדי לעבור דרך שדה או רשימה חוזרים, מלבד שימוש ספציפי עם האופרטור :.

יש אופרטור

ב-Ad Manager API יש תמיכה באופרטור :, שמשמעותו 'יש'. אפשר להשתמש בו עם אוספים (שדות חוזרים או מפות), הודעות ומחרוזות, וההתנהגות שלו משתנה מעט בכל מקרה.

שאילתת שדות מחרוזת כדי לבדוק אם המחרוזת מכילה מחרוזת משנה תואמת:

דוגמה	משמעות
r.displayName:"_250x250"	הפונקציה מחזירה את הערך True אם שדה המחרוזת r.displayName מכיל את מחרוזת המשנה _250x250.

שאילתה של שדות חוזרים כדי לבדוק אם המבנה החוזר מכיל רכיב תואם:

דוגמה	משמעות
r:42	הפונקציה מחזירה את הערך True אם r מכיל את הערך 42.
r.foo:42	הפונקציה מחזירה את הערך True אם r מכיל רכיב e כך ש-e.foo = 42.

חשוב: מסננים לא יכולים לשלוח שאילתות לגבי ערך של רכיב ספציפי בשדה חוזר. לדוגמה, e.0.foo = 42 ו-e[0].foo = 42 הם לא מסננים חוקיים.

אפשר לשלוח שאילתות למפות, למבנים ולהודעות כדי לבדוק אם שדה מסוים נמצא במפה או אם יש ערך ספציפי:

דוגמה	משמעות
m:foo	הפונקציה מחזירה את הערך True אם m מכיל את המפתח foo.
m.foo:*	הפונקציה מחזירה את הערך True אם m מכיל את המפתח foo.
m.foo:42	הפונקציה מחזירה את הערך True אם הערך של m.foo הוא 42.

כשמעיינים בהודעות, שדה נחשב נוכח רק אם יש לו ערך שאינו ערך ברירת המחדל.

מגבלות

שירותים ספציפיים יכולים לציין מבנה או הגבלות נוספים לשאילתות סינון, בנוסף למה שמוגדר כאן.

הזמנה

רוב המשאבים תומכים בסדר לפי שיטות List. במסמכי העזרה של השיטה List מוסבר מהו ההתנהגות המדויקת של המשאב ואילו שדות נתמכים למטרות מיון.

התחביר של שדות orderBy הוא רשימה של שמות שדות מופרדים בפסיקים. לדוגמה: "foo,bar".

סדר המיון שמוגדר כברירת מחדל הוא עולה. כדי לציין סדר יורד בשדה, מוסיפים את הסיומת " desc". לדוגמה: "foo desc, bar".

המערכת מתעלמת מתווים מיותרים של רווחים בתחביר. הערכים "foo, bar desc",‏ " foo , bar desc " ו-"foo,bar desc" זהים.

שדות משנה מצוינים באמצעות אופרטור הניווט. לדוגמה: foo.bar או address.street.