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

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

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

דוגמה:

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.