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

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

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

מאמרי עזרה

הקטע קובץ עזר כולל את כל המידע הדרוש כדי להשתמש בצורה נכונה בכל אחד מפריטי המידע שנוצרו בתהליך הפיתוח (Artifact). יש דף אחד לכל משאב, לדוגמה ad_group campaign הדפים segments ו-metrics רשימה של כל השדות הזמינים של הפלחים והמדדים.

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

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

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

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

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

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

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

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

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

העמודה 'מדדים'

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

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

משאבים לפילוח

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

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

ניתן לבחירה באמצעות

חלק מהשדות של segments לא תואמים למשאבים, לפלחים ולפלחים אחרים מדדים.

הדף segments כולל שדה ניתן לבחירה עם מתרחב לכל שדה 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

אפס מדדים

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

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

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

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

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