יצירת דוחות חיפוש ב-Search Ads 360 Reporting API

בקטעים הבאים מוסבר איך יוצרים דוחות חיפוש ב-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.

הבקשה מורכבת מ-POST של HTTP לשרת של 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

מסמכי עזר

הקטע Reference כולל את כל המידע הדרוש לשימוש נכון בכל ארטיפקט. יש דף אחד לכל משאב, למשל ad_group ו-campaign. בדפים segments ו-metrics מפורטים כל השדות של המדדים והפלחים הזמינים.

יש משאבים, פלחים ומדדים שלא תואמים ולא ניתן להשתמש בהם ביחד, ויש כאלה שתואמים לחלוטין ומשתלימים זה עם זה. כל דף משאב כולל את הפרטים הבאים (אם הם זמינים ורלוונטיים) ועוד:

משאבים שמשויכים

בחלק מהמשאבים, יכול להיות שתוכלו לאחד משאבים קשורים באופן משתמע על ידי בחירת השדות שלהם יחד עם השדות של המשאב בפסקה FROM. לדוגמה, המשאב campaign הוא משאב שמשויך למשאב ad_group. המשמעות היא שאפשר לכלול בשאילתה שדות כמו campaign.id ו-campaign.bidding_strategy_type כשמשתמשים ב-ad_group בתנאי FROM.

בקטע משאבים משויכים מפורטים המשאבים המשויכים הזמינים. לא לכל המשאבים יש משאבים משויכים.

העמודה 'שדות משאבים'

כל השדות של המשאב נכללים בעמודה Resource fields. כל שדה משאב מקשר לפרטים נוספים על השדה, כולל התיאור, הקטגוריה, סוג הנתונים, כתובת ה-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 יש תפריט נפתח Selectable with לכל שדה segments, שמציג את כל שדות המשאבים, שדות ה-metrics ושדות ה-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

אם משאב מוחזר עם סוג הנתונים UNKNOWN enum, המשמעות היא שהסוג לא נתמך באופן מלא בגרסה של ה-API. יכול להיות שהמשאבים האלה נוצרו באמצעות ממשקים אחרים. לדוגמה, קמפיין או מודעה חדשים הוצגו בממשק המשתמש של Search Ads 360, אבל עדיין אין תמיכה בהם בגרסה של ה-API שאליה אתם שולחים את השאילתה.

עדיין אפשר לבחור מדדים כשסוג המשאב הוא UNKNOWN, אבל חשוב לזכור את הנקודות הבאות:

• יכול להיות שסוג UNKNOWN של משאב יקבל תמיכה בשלב מאוחר יותר, אבל הוא יכול להישאר בתור UNKNOWN ללא הגבלת זמן.
• אובייקטים חדשים מסוג UNKNOWN עשויים להופיע בכל שלב. האובייקטים האלה תואמים לאחור כי ערך המאפיין enum כבר זמין. אנחנו מוסיפים את המשאבים האלה בהדרגה, לפי זמינותם, כדי שתהיה לכם תמונה מדויקת של החשבון. המשאב UNKNOWN עשוי להופיע בגלל פעילות חדשה בחשבון דרך ממשקים אחרים, או בגלל שהתמיכה במשאב הופסקה באופן רשמי.
• יכול להיות שלמשאבי UNKNOWN יהיו מדדים מפורטים שאפשר להריץ עליהם שאילתות.
• בדרך כלל, המשאבים מסוג UNKNOWN גלויים במלואם בממשק המשתמש של Search Ads 360.