הפרמטר של מחרוזת השאילתה 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