מסננים

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

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

דוגמה	משמעות
orders.updateTime > "2024-01-01T00:00:00-5:00"	הצגת הזמנות עם updateTime אחרי 1 בינואר 2024 באזור הזמן החוף המזרחי (EST24)
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 ל-REST תומך באופרטורים הבינאריים AND ו-OR.

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

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

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

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

ה-API ל-REST של Ad Manager מספק את האופרטורים המאוחדים NOT ו--. אפשר להשתמש במונחים האלה לסירוגין.

מפעיל	דוגמה	משמעות
NOT	NOT a	True אם הערך של a אינו TRUE.
-	-a	True אם הערך של a אינו TRUE.

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

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

מפעיל	דוגמה	משמעות
=	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"
• הערכים צריכים להיות ייצוג של מחרוזות של טיפוסים בני מנייה (enum) (תלוי אותיות רישיות).
• הבוליאניים מצפים לערכים של true ו-false.
• מספרים מצפים לייצוגים של מספרים שלמים או צפים. בצפים, יש תמיכה במעריך. דוגמה: 2.997e9
• משכי הזמן צריכים לצפות לייצוג מספרי ואחריו סיומת s (לשניות). דוגמאות: "20s", "1.2s".
• חותמות זמן צריכות לקבל מחרוזת בפורמט RFC-3339. לדוגמה: "2012-04-21T11:30:00-04:00". יש תמיכה בקיזוזים לשעון UTC.

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

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

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

דוגמה	משמעות
a = "*.foo"	הערך הוא True אם a מסתיים ב- ".foo".

אופרטור של חצייה

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

דוגמה	משמעות
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 REST API תומך באופרטור :, שמשמעותו היא 'has'. אפשר להשתמש בו עם אוספים (שדות חוזרים או מפות), הודעות ומחרוזות, והתנהגותו שונה מעט בכל מקרה.

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

דוגמה	משמעות
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 הם לא מסננים חוקיים.

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

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

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

מגבלות

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

הזמנה

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

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

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

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