בקטעים הבאים מוסבר איך ליצור דוחות חיפוש ב-Search Ads 360 Reporting API.
חיפוש שירות
Search Ads 360 Reporting API הוא שירות מיוחד לחיפוש ולדיווח.
SearchAds360Service
הוא שירות מאוחד לאחזור אובייקטים ודיווח, שמספק שתי שיטות חיפוש: SearchStream
ו-Search
. החיפושים מועברים במחרוזת שאילתה שכתובה בשפת השאילתות של Search Ads 360. אפשר להגדיר שאילתות כדי:
- אחזור תכונות ספציפיות של אובייקטים.
- אחזור מדדי ביצועים של אובייקטים על סמך טווח תאריכים.
- סדר אובייקטים על סמך המאפיינים שלהם.
- סינון התוצאות באמצעות תנאים שמציינים אילו אובייקטים להחזיר
- הגבלת מספר האובייקטים המוחזרים.
שתי שיטות החיפוש מחזירות את כל השורות שתואמות לשאילתה שלך. לדוגמה, כשמאחזרים את העמודות campaign.id
, campaign.name
ו-metrics.clicks
, ה-API מחזיר
SearchAds360Row
שמכיל אובייקט של קמפיין עם השדות id
ו-name
שלו, ואובייקט metrics
עם שדה clicks
שלו.
שיטות חיפוש
SearchStream
שולחת בקשה אחת ויוצרת חיבור קבוע עם Search Ads 360 Reporting API, בלי קשר לגודל הדוח.
- ההורדה של חבילות נתונים מתחילה באופן מיידי, עם כל התוצאה שנשמרה במאגר נתונים זמני.
- הקוד יכול להתחיל לקרוא את הנתונים במאגר הזמני בלי לחכות עד שכל השידור יסתיים.
Search
שולחת כמה בקשות עם עימוד להורדת הדוח כולו.
SearchStream
בדרך כלל מציע ביצועים טובים יותר כי הוא מבטל את הזמן ברשת הלוך ושוב שנדרש כדי לבקש דפים ספציפיים. מומלץ להשתמש ב-SearchStream
בכל הדוחות שכוללים יותר מ-10,000 שורות. אין הבדל משמעותי בביצועים בין השיטות לדוחות קטנים יותר (פחות מ-10,000 שורות).
השיטה שבה משתמשים לא משפיעה על המכסות והמגבלות של ה-API: שאילתה יחידה או דוח אחד נספרים כפעולה אחת, גם אם התוצאות לא משויכות לדפים או לאי-שידור.
שאילתת חיפוש לדוגמה
השאילתה לדוגמה הבאה מציגה נתוני ביצועים של חשבון ב-30 הימים האחרונים לפי קמפיין, בפילוח לפי מכשיר:
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
יצירת בקשה
כדי לשלוח בקשה, צריך להעביר מחרוזת customer_id
ומחרוזת query
לממשק SearchAds360Service.SearchStream
או לממשק SearchAds360Service.Search
.
הבקשה מורכבת מ-HTTP POST
לשרת Search Ads 360 Reporting API באחת מכתובות ה-URL הבאות:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search
לפניכם דוגמה מלאה להגדרת הדוח ל-searchStream
שמופיעה בבקשת HTTP מסוג POST
:
POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1 Host: searchads360.googleapis.com User-Agent: curl Content-Type: application/json Accept: application/json Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN] Parameters: { "query" : "SELECT campaign.name, campaign.status, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS" }
עיבוד תשובה
SearchAds360Service
מחזירה רשימה של SearchAds360Row
אובייקטים.
כל SearchAds360Row
מייצג אובייקט שהוחזר על ידי השאילתה. כל אובייקט מכיל קבוצת מאפיינים שמאוכלסים בהתאם לשדות שהתבקשו בסעיף SELECT
של השאילתה. מאפיינים שלא נכללים במשפט SELECT
לא מאוכלסים באובייקטים שבתגובה.
לדוגמה, השאילתה שלמטה מאכלסת כל אובייקט SearchAds360Row
רק עם campaign.id
, campaign.name
ו-campaign.status
. מאפיינים אחרים כמו campaign.engine_id
או campaign.bidding_strategy_type
לא נכללים.
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
מסמכי עזר
הקטע קובץ עזר כולל את כל המידע הדרוש כדי להשתמש בצורה נכונה בכל ארטיפקט. לכל משאב יש דף אחד, לדוגמה ad_group
ו-campaign
.
בדפים segments
ו-metrics
מופיעים כל השדות הזמינים של הפלחים והמדדים.
יש משאבים, פלחים ומדדים שלא תואמים ואי אפשר להשתמש בהם יחד, ואחרים תואמים לחלוטין ומשלימים זה את זה. כל דף משאב כולל את הפרטים הבאים (אם הם זמינים ומתאימים) ועוד:
- משאבים משויכים
בחלק מהמשאבים ייתכן שתהיה אפשרות לאחד משאבים קשורים באופן מרומז על ידי בחירת השדות שלהם יחד עם שדות המשאב בסעיף
FROM
. לדוגמה, המשאבcampaign
הוא משאב מיוחס של המשאבad_group
. כלומר, אפשר לכלול בשאילתה שדות כמוcampaign.id
ו-campaign.bidding_strategy_type
כשמשתמשים ב-ad_group
בסעיףFROM
.בקטע משאבים משויכים מפורטים המשאבים הזמינים עם שיוך (Attribution). לא לכל המשאבים יש משאבים משויכים.
- העמודה 'שדות משאבים'
כל השדות של המשאב נכללים בעמודה שדות משאבים. כל שדה משאב מכיל קישורים לפרטים נוספים על השדה, כולל התיאור, הקטגוריה, סוג הנתונים, סוג כתובת ה-URL וההגדרות שניתנות לסינון, ניתנות לבחירה, למיון וחוזרות.
- העמודה 'פלחים'
לא כל שדות הפלח ניתנים לבחירה במשאב נתון.
בעמודה Segments מופיעים השדות
segments
שבהם אפשר להשתמש באותו סעיףSELECT
שבו מופיעים שדות המשאב. כל שדה מכיל קישור לפרטים מלאים של השדה, כולל התיאור, הקטגוריה, סוג הנתונים, סוג כתובת ה-URL וההגדרות שניתנות לסינון, לאפשרות לבחירה, למיון ולחזרה. אם אתם משתמשים במשאב בסעיףFROM
, תוכלו להשתמש בתפריט הנפתח Yes/No כדי לסנן את הפלחים שאינם זמינים.- העמודה 'מדדים'
לא כל שדות המדדים זמינים לבחירה במשאב נתון.
בעמודה Metrics מפורטים השדות
metrics
שבהם אפשר להשתמש באותו סעיףSELECT
שבו מופיעים שדות המשאב. כל שדה מכיל קישור לפרטים מלאים של השדה, כולל התיאור, הקטגוריה, סוג הנתונים, סוג כתובת ה-URL וההגדרות שניתנות לסינון, לאפשרות לבחירה, למיון ולחזרה. אם משתמשים במשאב בסעיףFROM
, השתמשו בתפריט הנפתח Yes/No כדי לסנן מדדים שלא זמינים.
- פילוח משאבים
בחלק מהמשאבים יש שדות פילוח שאפשר לבחור כשהמשאב נמצא בסעיף
FROM
. לדוגמה, אם בוחרים שדה משאבcampaign
, כמוcampaign.name
, כשמשתמשים ב-campaign_budget
בסעיף שלFROM
, הפונקציהcampaign.resource_name
תוחזר באופן אוטומטי ותפלח אותו, כיcampaign
הוא משאב הפילוח שלcampaign_budget
.הקטע משאבים לפילוח מפרט את משאבי הפילוח הזמינים. לא לכל המשאבים יש משאבי פילוח.
- ניתן לבחירה עם
חלק מהשדות של
segments
לא תואמים למשאבים, לפלחים ולמדדים אחרים.בדף
segments
יש שדה ניתן לבחירה עם שניתן לבחור בכל שדהsegments
, שמפורטים בו כל שדות המשאבים התואמים,metrics
שדותsegments
ושדותsegments
אחרים שאפשר לכלול בסעיףSELECT
.
פילוח
תוכלו לפלח את תוצאות החיפוש על ידי הוספת השדה segments.FIELD_NAME
לסעיף SELECT
בשאילתה.
לדוגמה, segments.device
בשאילתה שלמטה יפיק דוח עם שורה לimpressions
של כל מכשיר במשאב שצוין בסעיף FROM
.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
התוצאות שמוחזרות על ידי SearchAds360Service.SearchStream
נראות בערך כך במחרוזת ה-JSON הבאה:
{
"results":[
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"10922"
},
"segments":{
"device":"MOBILE"
}
},
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"28297"
},
"segments":{
"device":"DESKTOP"
}
},
...
]
}
ראו segments
רשימה של שדות הפלח הזמינים לשימוש.
פלחים מרובים
אפשר לציין מספר פלחים בסעיף SELECT
של השאילתה. התשובה מכילה אובייקט SearchAds360Row
אחד לכל שילוב של המכונה של המשאב הראשי שצוין בסעיף FROM
, ואת הערך של כל שדה segment
שנבחר.
לדוגמה, השאילתה הבאה תחזיר שורה אחת לכל שילוב של campaign
, segments.ad_network_type
ו-segments.date
.
SELECT
segments.ad_network_type
segments.date
FROM campaign
חשוב לשים לב שהתוצאות מפולחות באופן לא מפורש לפי כל מכונה של המשאב הראשי, אבל לא לפי הערכים של השדות הנפרדים שנבחרו.
השאילתה לדוגמה הבאה מציגה תוצאות של שורה אחת לכל קמפיין, ולא שורה אחת לכל ערך ייחודי של השדה campaign.status
.
SELECT
campaign.status,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
פילוח מרומז
כל דוח מפולח בהתחלה לפי המשאב שצוין בסעיף FROM
. המדדים מפולחים לפי השדה resource_name
של המשאב הזה
השאילתה לדוגמה מחזירה אוטומטית את הערך ad_group.resource_name
ומשתמשת בו באופן מרומז כדי לפלח מדדים ברמת ad_group
.
SELECT metrics.impressions
FROM ad_group
מחרוזת ה-JSON שהוחזרה נראית כך:
{
"results":[
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/2222222222"
},
"metrics":{
"impressions":"237"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/33333333333"
},
"metrics":{
"impressions":"15"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/44444444444"
},
"metrics":{
"impressions":"0"
}
}
]
}
פלחי תאריכים עיקריים
ניתן להשתמש בפלחי תאריך עיקריים בסעיף WHERE
על מנת לציין תאריך או תקופת זמן.
שדות הפלחים הבאים נקראים פלחי תאריך ליבה: segments.date
, segments.week
, segments.month
, segments.quarter
ו-segments.year
.
השאילתה לדוגמה הזו מחזירה את מדדי הקמפיין clicks
מ-30 הימים האחרונים.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
השדות של פלחי תאריך מרכזיים הם חריג לכלל הכללי, שלפיו לא ניתן להשתמש בשדה פלחים בסעיף WHERE
, אלא אם כוללים את השדה גם בסעיף SELECT
. למידע נוסף, ראו סינון אסור.
כללים לגבי פלחי תאריך עיקריים:
אפשר להשתמש בשדה תאריך מרכזי בסעיף
WHERE
בלי לכלול אותו בסעיףSELECT
. אם רוצים, אפשר גם לכלול את השדה בשני הסעיפים.השאילתה לדוגמה הזו מחזירה מדדים של
clicks
לפי שם הקמפיין בטווח התאריכים. חשוב לשים לב ש-segments.date
לא נכלל בסעיףSELECT
.SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
אם אתם כוללים שדה תאריך מרכזי בסעיף
SELECT
, עליכם לציין תאריך או טווח תאריכים סופיים בסעיףWHERE
. השדות שצוינו בסעיףSELECT
ובסעיףWHERE
לא צריכים להיות זהים.השאילתה לדוגמה מחזירה מדדים של
clicks
לפי שם הקמפיין, בפילוח לפי חודש לכל הימים בטווח התאריכים.SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
תאריכים בתקן ISO 8601
צריך להשתמש בפורמט YYYY-MM-DD
(ISO 8601) כדי לציין תאריכים וטווחי תאריכים, לדוגמה:
WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'
WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'
כשמדובר בפלחי תאריך מרכזיים שנדרשת בשבילם תקופת זמן (segments.week
, segments.month
, segments.quarter
), אפשר להשתמש באופרטור =
עם היום הראשון של פרק הזמן. לדוגמה:
WHERE segments.month = '2022-06-01'
תאריכים מוגדרים מראש
אפשר גם להשתמש בתאריכים ובטווחי התאריכים המוגדרים מראש:
תאריכים מוגדרים מראש | |
---|---|
TODAY |
רק היום. |
YESTERDAY |
אתמול בלבד. |
LAST_7_DAYS |
7 הימים הקודמים לא כולל היום. |
LAST_BUSINESS_WEEK |
שבוע העסקים הקודם של 5 ימים (שני עד שישי). |
THIS_MONTH |
כל הימים בחודש הנוכחי. |
LAST_MONTH |
כל הימים בחודש הקודם. |
LAST_14_DAYS |
14 הימים הקודמים לא כולל היום. |
LAST_30_DAYS |
30 הימים הקודמים לא כולל היום. |
THIS_WEEK_SUN_TODAY |
פרק הזמן בין יום ראשון הקודם ליום הנוכחי. |
THIS_WEEK_MON_TODAY |
התקופה בין יום שני הקודם ליום הנוכחי. |
LAST_WEEK_SUN_SAT |
תקופה של 7 ימים החל מיום ראשון הקודם. |
LAST_WEEK_MON_SUN |
תקופה של 7 ימים החל מיום שני הקודם. |
דוגמה:
WHERE segments.date DURING LAST_30_DAYS
אפס מדדים
כשמריצים שאילתה, יכול להיות שיופיעו מדדים עם ערך אפס עבור ישויות מסוימות. איך לטפל באפס מדדים בשאילתות.
סוגי טיפוסים בני מנייה לא ידועים
אם משאב מוחזר עם סוג הנתונים 'טיפוסים בני מנייה (enum)' UNKNOWN
, המשמעות היא שהסוג לא נתמך באופן מלא בגרסת ה-API. יכול להיות שהמשאבים האלה נוצרו באמצעות ממשקים אחרים. לדוגמה, מודעה או קמפיין חדשים מוצגים בממשק המשתמש של Search Ads 360, אבל הם עדיין לא נתמכים בגרסת ה-API שעליה אתם שולחים את השאילתה.
עדיין אפשר לבחור מדדים כשהמשאב הוא מסוג UNKNOWN
, אבל חשוב לזכור:
- יכול להיות שבהמשך תהיה תמיכה במשאב מסוג
UNKNOWN
, אבל הוא יכול להישארUNKNOWN
ללא הגבלת זמן. - בכל שלב יכולים להופיע אובייקטים חדשים מסוג
UNKNOWN
. האובייקטים האלה תואמים לאחור כי ערך ה-enum כבר זמין. אנחנו מוסיפים משאבים עם השינוי הזה כדי שתהיה לכם תצוגה מדויקת של החשבון. המשאבUNKNOWN
עשוי להופיע בגלל פעילות חדשה בחשבון דרך ממשקים אחרים, או בגלל שהתמיכה במשאב הופסקה באופן רשמי. - יכול להיות שצורפו מדדים מפורטים ל-
UNKNOWN
משאבים שאפשר להריץ עליהם שאילתות. - משאבים מסוג
UNKNOWN
בדרך כלל מוצגים במלואם בממשק המשתמש של Search Ads 360.