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יכולים להופיע בכל שלב. האובייקטים האלה תואמים לדורות קודמים כי ערך ה-enumUNKNOWNקיים בכל enum ב-API. המשאבים מוחזרים עםUNKNOWNכדי שתקבלו תמונה מדויקת של מדדי הביצועים הכוללים של החשבון. - למשאבים מסוג
UNKNOWNיכולים להיות מדדים מפורטים שאפשר לשלוח אליהם שאילתות. - בדרך כלל, משאבי
UNKNOWNגלויים לחלוטין בממשק המשתמש של Google Ads. - באופן כללי, אי אפשר לשנות משאבים מסוג
UNKNOWNבאמצעות ה-API.
פילוח
התשובה מכילה GoogleAdsRow אחד לכל שילוב של:
- מופע של המשאב הראשי שצוין בסעיף
FROM - הערך של כל שדה
segmentsשנבחר
לדוגמה, התשובה לשאילתה שבוחרת את FROM campaign וכוללת את segments.ad_network_type ו-segments.date בסעיף SELECT מכילה שורה אחת לכל שילוב של:
campaignsegments.ad_network_typesegments.date
התוצאות מפולחות באופן מובלע לפי כל מופע של המשאב הראשי, ולא לפי הערכים של השדות הספציפיים שנבחרו. לדוגמה,
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
מחזירה שורה אחת לכל קמפיין, ולא שורה אחת לכל ערך ייחודי בשדה campaign.status.