מסננים

ב-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 הוא לא True.
-	-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 יש משמעות פנימית רק כאשר משתמשים בהם בהקשר של הפניה לשדה שהוקלד.

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

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

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

אופרטור מעבר

‏Ad Manager API תומך באופרטור ., שמציין טרaversal דרך הודעה, מפה או מבנה.

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

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

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

כולל מפעיל

ב-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.

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

מגבלות

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

הזמנה

ב-Ad Manager API יש תמיכה בסדר עולה בשיטות List. התחביר של שדות orderBy הוא רשימה מופרדת בפסיקים של שמות שדות. לדוגמה: "foo,bar".

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

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

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