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

מאמרי עזרה

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

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

משאבים עם ייחוס

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

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

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

כל השדות של המשאב נכללים בעמודה Resource fields. כל שדה משאב מקשר לפרטים נוספים על השדה, כולל התיאור, הקטגוריה, סוג הנתונים, כתובת ה-URL של הסוג וההגדרה של אפשרות הסינון, הבחירה, המיון והחזרה.

העמודה 'פלחים'

לא ניתן לבחור את כל שדות הפלחים עם משאב נתון.

בעמודה Segments מפורטים השדות segments שאפשר להשתמש בהם באותו סעיף SELECT כמו השדות של המשאב. כל שדה מקושר לפרטים מלאים על השדה, כולל התיאור, הקטגוריה, סוג הנתונים, כתובת ה-URL של הסוג וההגדרה של אפשרות הסינון, הבחירה, המיון והחזרה. אם אתם משתמשים במשאב בסעיף FROM, אתם יכולים להשתמש בתפריט הנפתח כן/לא כדי לסנן פלחים שלא זמינים.

עמודת מדדים

לא ניתן לבחור את כל שדות המדדים עם משאב נתון.

בעמודה Metrics מפורטים השדות metrics שאפשר להשתמש בהם באותו סעיף SELECT כמו השדות של המשאב. כל שדה מקושר לפרטים מלאים על השדה, כולל התיאור, הקטגוריה, סוג הנתונים, כתובת ה-URL של הסוג וההגדרה של אפשרות הסינון, הבחירה, המיון והחזרה. אם אתם משתמשים במשאב בסעיף FROM, אתם יכולים להשתמש בתפריט הנפתח כן/לא כדי לסנן מדדים שלא זמינים.

פילוח משאבים

לחלק מהמשאבים יש שדות משאבים לפילוח שאפשר לבחור כשהמשאב נמצא בסעיף FROM. לדוגמה, אם בוחרים שדה משאב של campaign, כמו campaign.name, כשמשתמשים ב-campaign_budget בפסקה FROM, המערכת תחזיר ותפלח אוטומטית את campaign.resource_name, כי campaign הוא משאב פילוח של campaign_budget.

בקטע Segmenting resources (פילוח משאבים) מופיעה רשימה של משאבי פילוח זמינים. לא לכל המשאבים יש משאבי פילוח.

ניתן לבחירה עם

חלק מהשדות של 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'

תאריכים מוגדרים מראש

אפשר גם להשתמש בתאריכים ובטווחים הבאים של תאריכים שמוגדרים מראש:

דוגמה:

WHERE segments.date DURING LAST_30_DAYS

אפס מדדים

כשמריצים שאילתה, יכול להיות שיוצגו מדדים עם ערך אפס עבור חלק מהישויות. איך מטפלים במדדים עם ערך אפס בשאילתות

סוגי enum לא ידועים

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

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

• יכול להיות שסוג המשאב UNKNOWN ייתמך בהמשך, אבל יכול להיות שהוא יישאר UNKNOWN ללא הגבלת זמן.

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

• יכול להיות שלמשאבים מסוימים מצורפים מדדים מפורטים שאפשר לשלוח לגביהם שאילתות.UNKNOWN

• בדרך כלל אפשר לראות את כל המשאבים מסוג UNKNOWN בממשק המשתמש של Search Ads 360.