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

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

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

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

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

מידע נוסף על חלוקה לדפים לעומת סטרימינג

שליחת בקשה

‫GoogleAdsService.SearchStream צריך להיות SearchGoogleAdsStreamRequest, ו-GoogleAdsService.Search צריך להיות SearchGoogleAdsRequest. שני סוגי הבקשות כוללים:

• ‫customer_id
• שאילתת Google Ads Query Language‏ 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.