יצירת דוחות חיפוש ב-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.

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