מתבצע אחזור של אובייקטים

‫GoogleAdsService הוא שירות מאוחד לאחזור אובייקטים ולדיווח ב-Google Ads API. בשירות יש שיטות שמאפשרות:

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

הפונקציה GoogleAdsService יכולה להחזיר תוצאות בשתי דרכים:

  • GoogleAdsService.SearchStream מחזירה את כל השורות בתגובת סטרימינג אחת, וזה יעיל יותר לקבוצות גדולות של תוצאות (יותר מ-10,000 שורות). מומלץ להשתמש בשיטה הזו אם האפליקציה מורידה קבוצות מלאות של תוצאות או מעבדת שורות כסטרימינג.
  • GoogleAdsService.Search מחלק תשובות גדולות לדפים של תוצאות שאפשר לנהל. האפשרות הזו שימושית אם האפליקציה האינטראקטיבית שלכם מציגה דף תוצאות אחד בכל פעם.

מידע נוסף על דפדוף לעומת סטרימינג

שליחת בקשה

הפונקציה GoogleAdsService.SearchStream מצפה לקבל SearchGoogleAdsStreamRequest, והפונקציה GoogleAdsService.Search מצפה לקבל SearchGoogleAdsRequest. שני סוגי הבקשות כוללים:

  • customer_id
  • שאילתה בשפת השאילתות של Google Ads‏ (query) שמציינת את המשאב שרוצים לשלוח אליו שאילתה, את המאפיינים, הפלחים והמדדים שרוצים לאחזר, ואת התנאים להגבלת האובייקטים שיוחזרו.

בהתאם לשיטה, הבקשה תומכת גם בשדות ספציפיים לשיטה:

  • ‫SearchGoogleAdsStreamRequest (SearchStream בלבד):
    • פרמטר אופציונלי summary_row_setting לבקשת שורת סיכום שמכילה מדדים נצברים
  • ‫SearchGoogleAdsRequest (Search בלבד):
    • page_token אופציונלי לאחזור של קבוצת התוצאות הבאה כשמשתמשים בחלוקה לדפים (page_size קבוע ב-10,000 שורות; הגדרה של page_size בבקשה גורמת לשגיאת RequestError.PAGE_SIZE_NOT_SUPPORTED)
    • הודעת search_settings אופציונלית להגדרת return_summary_row,‏ return_total_results_count ו-omit_results
    • ערך בוליאני אופציונלי validate_only לאימות השאילתה בלי להריץ אותה

מידע נוסף על שפת השאילתות של Google Ads זמין במדריך בנושא שפת השאילתות של Google Ads.

עיבוד תשובה

ה-GoogleAdsService מחזיר רשימה של אובייקטים מסוג GoogleAdsRow (בתוך קבוצות SearchGoogleAdsStreamResponse בסטרימינג או ב-SearchGoogleAdsResponse עם דפים).

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

לדוגמה, למרות של-ad_group_criterion יש מאפיין status, השדה status של המאפיין ad_group_criterion של השורה לא מאוכלס בתגובה לשאילתה שבה הסעיף SELECT לא כולל את ad_group_criterion.status. באופן דומה, המאפיין campaign של השורה לא מאוכלס אם הסעיף SELECT לא כולל שדות מהמשאב campaign.

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

סוגי enum מסוג UNKNOWN ו-UNSPECIFIED

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

הנה כמה דברים שכדאי לזכור:

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

פילוח

התשובה מכילה GoogleAdsRow אחד לכל שילוב של:

  • מופע של המשאב הראשי שצוין בסעיף FROM
  • הערך של כל שדה segments שנבחר

לדוגמה, התשובה לשאילתה שבוחרת את FROM campaign וכוללת את segments.ad_network_type ו-segments.date בסעיף SELECT מכילה שורה אחת לכל שילוב של:

  • campaign
  • segments.ad_network_type
  • segments.date

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

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

מחזירה שורה אחת לכל קמפיין, ולא שורה אחת לכל ערך ייחודי בשדה campaign.status.