הפרמטר של מחרוזת השאילתה filters מגביל את הנתונים שמוחזרות בדוח של AdSense Management API. כשמשתמשים בפרמטר filters, מוסיפים מאפיין שלפיו רוצים לסנן, ואחריו את ביטוי המסנן.
שאילתות מסוננות מגבילות את השורות שכלולות בתוצאה. כל שורה בתוצאה נבדקת מול המסנן: אם המסנן תואם, השורה נשמרת ואם היא לא תואמת, השורה מושמטת.
- קידוד כתובות URL: ספריות הלקוח מקודדות באופן אוטומטי את האופרטורים של המסננים. עם זאת, אם שולחים בקשות ישירות לפרוטוקול, צריך לקודד באופן מפורש את אופרטורים של מסננים, כפי שמתואר בטבלה שלמטה.
- עדיפות סינון: הסינון מתבצע לפני שמאפיינים נצברים, כך שהמדדים שהוחזרו מייצגים את הסכום הכולל של המאפיינים הרלוונטיים בלבד.
תחביר הסינון
מסנן יחיד משתמש בצורה הבאה:
name operator expression
בתחביר הזה:
- name – שם המאפיין שבו רוצים לסנן.
לדוגמה: המערכת תסנן את
AD_CLIENT_IDלפי מזהה הלקוח של המודעה. - אופרטור — מגדיר את סוג התאמת המסנן שבו יש להשתמש.
- expression – מציין את הערכים שייכללו בתוצאות.
אפשר להשתמש בכל המאפיינים שחלים על המדדים המדווחים עליהם, מלבד מאפיינים שקשורים לתאריכים (DATE, WEEK ו-MONTH). כדי לסנן לפי תאריך, צריך לציין את טווח התאריכים של הדוח במקום זאת.
אופרטורים של מסננים
יש שני אופרטורים של מסננים. כתובות ה-URL צריכות להיות מקודדות כדי להיכלל במחרוזות שאילתה בכתובות URL.
| מפעיל | תיאור | טופס מקודד של כתובת URL | דוגמה |
|---|---|---|---|
== |
התאמה מדויקת | %3D%3D |
מדדים מצטברים שבהם שם המדינה הוא קנדה:
filters=COUNTRY_NAME%3D%3DCanada |
=@ |
מכיל מחרוזת משנה | %3D@ |
מדדים נצברים שבהם שם המדינה מכיל את המילה ישראל,
שתואם לארצות הברית ולבריטניה, לדוגמה:
filters=COUNTRY_NAME%3D@United |
ביטויי סינון
יש כמה כללים חשובים לגבי ביטויי סינון:
- תווים שמורים של כתובות URL — קידוד ה-URL של תווים כמו
&חייב להתבצע כרגיל. ספריות לקוח יטפלו בזה עבורך, כך שעליך לדאוג לגבי הקידוד הזה רק אם אתה מבצע קריאות ישירות לפרוטוקול. - תווים שמורים – צריך לסמן את הפסיק והקו הנטוי בתו בריחה כשהם מופיעים בביטוי.
- לוכסן הפוך
\\ - פסיק
\,
- לוכסן הפוך
הערה: חשוב להקפיד להשתמש בתו בריחה (escape) לפני פסיקים, כדי להימנע משימוש ב תווי בריחה (escape) כפולים.
שילוב מסננים
אפשר לשלב מסננים באמצעות לוגיקה בוליאנית OR ו-AND.
לוגיקת OR
הלוגיקה של OR מוגדרת באמצעות פסיק (,) בתוך
ביטוי המסנן.
דוגמה: (כל כתובת צריכה להיות מקודדת בקידוד)
קוד המדינה הוא (ארה"ב או בריטניה):
COUNTRY_CODE==US,COUNTRY_CODE==UK
לוגיקה
כדי להשיג את הלוגיקה של AND, צריך לספק כמה פרמטרים של מסננים, וכך לספק מערך של מסננים בספריות הלקוח.
דוגמה:
קוד המדינה הוא US וגם קוד המוצר הוא AFC:
filters=COUNTRY_CODE%3D%3DUS&filters=PRODUCT_CODE%3D%3DAFC
שילוב לוגיקת AND ו-OR
ניתן לשלב את לוגיקת AND ו-OR בביטוי אחד.
הערה: כל מסנן נבדק בנפרד לפני השילוב של כל המסננים בביטוי לוגי AND.
דוגמה:
קוד המדינה הוא (ארה"ב או בריטניה) וגם קוד המוצר הוא AFC:
filters=COUNTRY_CODE%3D%3DUS,COUNTRY_CODE%3D%3DUK&filters=PRODUCT_CODE%3D%3DAFC