שפת השאילתות של Google Ads

מונחים חשובים

משאב
ישות ב-Google Ads, כמו campaign או ad_group.
Segment
מאפיין שמשמש לקיבוץ נתונים, כמו segments.date או segments.device. כשכוללים פלחים בסעיף SELECT עם מדדים, המדדים מחולקים לפי פלח.
מדד
מדידת ביצועים, כמו metrics.impressions או metrics.clicks.
משאב משויך
משאב שמצורף באופן מרומז למשאב הראשי בפסקה FROM, ומאפשר לבחור את המאפיינים שלו יחד עם המאפיינים של המשאב הראשי.

שליחת שאילתה למידע על משאבים או מטא-נתונים

אפשר להשתמש בשפת השאילתות של Google Ads כדי לשלוח שאילתות ל-Google Ads API לגבי סוגי המידע הבאים:

  • משאבים והמאפיינים, הפלחים והמדדים שקשורים אליהם באמצעות GoogleAdsService Search או SearchStream: התוצאה משאילתת GoogleAdsService היא רשימה של מופעי GoogleAdsRow, כאשר כל GoogleAdsRow מייצג משאב.

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

  • מטא-נתונים על השדות והמשאבים שזמינים ב-GoogleAdsFieldService: השירות הזה מספק קטלוג של שדות שאפשר להריץ עליהם שאילתות, עם פרטים ספציפיים לגבי התאימות והסוג שלהם.

    התוצאה של שאילתת GoogleAdsFieldService היא רשימה של מופעי GoogleAdsField, וכל GoogleAdsField מכיל פרטים על השדה המבוקש.

פרטים נוספים על מבנה השאילתה זמינים במאמרים מבנה השאילתה ודקדוק של Google Ads Query Language.

שאילתה לגבי מאפייני משאבים

הנה דוגמה לשאילתה בסיסית לגבי מאפיינים של משאב הקמפיין, שממחישה איך להחזיר את מזהה הקמפיין, השם והסטטוס:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

השאילתה הזו מסודרת לפי מזהה הקמפיין. כל GoogleAdsRow שמתקבל מייצג אובייקט campaign שמכיל את השדות שנבחרו, כולל resource_name הקמפיין.

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

שאילתה למדדים

בנוסף למאפיינים שנבחרו למשאב מסוים, אפשר גם לשלוח שאילתות לגבי מדדים שקשורים למשאב:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

השאילתה הזו מסננת רק את הקמפיינים שהסטטוס שלהם הוא PAUSED ושקיבלו יותר מ-1,000 חשיפות, וממיינת אותם לפי מזהה הקמפיין. בכל GoogleAdsRow שמתקבל יאוכלס השדה metrics עם המדדים שנבחרו.

רשימה של מדדים שאפשר להריץ עליהם שאילתות זמינה במאמרי העזרה של Metrics.

שאילתות לגבי פלחים

בנוסף למאפיינים שנבחרו למשאב מסוים, אפשר גם לשאול לגבי קטעים קשורים:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

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

רשימה של פלחים שאפשר להריץ עליהם שאילתות מופיעה במאמרי העזרה בנושא Segments.

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

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

השאילתה הזו לא רק בוחרת מאפייני קמפיין, אלא גם מאחזרת מאפיינים קשורים מכל קמפיין שנבחר. כל GoogleAdsRow שמתקבל מייצג אובייקט campaign שמלא במאפייני הקמפיין שנבחרו, וגם במאפיין שיטת הבידינג שנבחר bidding_strategy.name.

כדי לדעת אילו משאבים משויכים זמינים לשאילתות של קמפיינים, אפשר לעיין במסמכי העזרה של Campaign.

שיטות מומלצות

  • כדי למנוע זמני תגובה ארוכים ופסק זמן, בוחרים רק את השדות שצריך.
  • כדי להימנע מעיבוד של מערכי תוצאות גדולים, כדאי להשתמש ב-LIMIT במהלך הפיתוח והבדיקה.
  • כדי לצמצם את העברת הנתונים ואת גודל התגובה, כדאי להחיל מסננים בסעיף WHERE.
  • כדאי להשתמש ב-GoogleAdsFieldService כדי לבדוק את התאימות של השדות ואת סוגי הנתונים לפני שיוצרים שאילתות מורכבות.
  • חשוב לזכור ששדות מסוימים, במיוחד כאלה שכוללים כמויות גדולות של נתונים או חישובים מורכבים, עלולים להגדיל את עלות השאילתה.

שינוי על סמך תוצאות השאילתה

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

  1. מריצים שאילתה לכל הקמפיינים PAUSED שבהם מספר החשיפות גדול מ-1,000.
  2. מקבלים את האובייקט Campaign מהשדה campaign של כל GoogleAdsRow בתגובה.
  3. משנים את הסטטוס של כל קמפיין מPAUSED לENABLED.
  4. מתקשרים אל CampaignService.MutateCampaigns עם הקמפיינים ששונו ועם FieldMask תואם כדי לעדכן אותם.

מטא-נתונים של שדות

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

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

אפשר להחליף את <INSERT_RESOURCE_OR_FIELD> בשאילתה הזו במשאב (כמו customer או campaign) או בשדה (כמו campaign.id,‏ metrics.impressions או ad_group.id).

רשימה של השדות שאפשר להריץ עליהם שאילתות מופיעה במסמכי התיעוד של GoogleAdsField.

הבדלים שספציפיים לגרסה

התחביר, הפסקאות והאופרטורים של שפת השאילתות של Google Ads זהים בכל הגרסאות הנתמכות של Google Ads API‏ (v23,‏ v24 ו-v25), אבל קטלוג המשאבים שאפשר להריץ עליהם שאילתות, הפלחים, המדדים והתנהגויות הדיווח שונים בין גרסה לגרסה. שליחת שאילתה אל GoogleAdsFieldService בנקודת הקצה של גרסת ה-API לטירגוט כדי לבדוק את השדות ואת כללי התאימות של הגרסה הזו:

  • מקורות מידע על יעדים שקשורים למחזור החיים של הלקוחות: בגרסה 25 ואילך, כל היעדים שקשורים למחזור החיים של הלקוחות (צירוף לקוחות חדשים, שימור לקוחות ושימור נאמנות) נשלפים ממקורות המידע המאוחדים goal וcampaign_goal_config, במקום customer_lifecycle_goal ו-campaign_lifecycle_goal (ששימשו ליעדים של צירוף לקוחות חדשים בגרסה 24 ובגרסאות קודמות, לצד goal ו-campaign_goal_config ליעדים של שימור לקוחות).
  • מדדים של צפיות בנכסים של התאמת כתובת URL סופית (FUE): בגרסה 25 ואילך, שליחת שאילתה של final_url_expansion_asset_view מחזירה את כל המדדים שניתן לבחור לצפייה. בגרסה 24 ובגרסאות קודמות, התשובות כוללות רק את הערכים metrics.conversions ו-metrics.conversions_value לקמפיינים למיקסום הביצועים ואת הערך metrics.impressions לקמפיינים לרשת החיפוש.
  • דיווח על מוצרים בקמפיינים לקידום אפליקציות: בגרסה v24 ואילך, מקור shopping_product מחזיר שורות של מוצרים בקמפיינים לקידום אפליקציות, בנוסף לקמפיינים של שופינג, קמפיינים למיקסום ביצועים, קמפיינים ליצירת ביקוש וקמפיינים של מודעות וידאו (בגרסה v23, קמפיינים לקידום אפליקציות לא נכללים בתוצאות של shopping_product).
  • משאבים, פלחים ומדדים שספציפיים לגרסה:
    • ‫v25 ואילך: כולל מקורות מידע למדידת עלייה (כמו lift_measurement_config), פלחים כמו segments.ad_sub_format_type ו-segments.loyalty_membership ומדדי התעניינות ב-YouTube ‏ (metrics.youtube_likes, ‏metrics.youtube_comments ו-metrics.youtube_shares). המדד local_services_lead.contact_details.email הוסר (אפשר לבחור אותו בגרסה v24 ובגרסאות קודמות).
    • ‫v24 ואילך: כולל את מקור המידע cart_data_sales_view,‏ segments.conversion_attribution_event_type ב-shopping_performance_view,‏ segments.mobile_device_platform ו-segments.ad_network_type ב-performance_max_placement_view. הסרה של campaign.video_brand_safety_suitability (הוחלף ב-customer.video_brand_safety_suitability),‏ segments.ad_sub_network_type ב-campaign_budget ו-segments.click_type ב-ad_group_asset,‏ campaign_asset ו-customer_asset (שאפשר לבחור רק בגרסה 23).
  • קוד השגיאה של נתונים מפורטים לפי תאריך: שאילתות שמפלחים לפי segments.date, segments.week או segments.hour (או מסננים לפי טווח תאריכים של פחות מחודש) מעבר לחלון של 37 חודשים אחורה מחזירות DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED בגרסה 24 ואילך (או DateRangeError.UNKNOWN בגרסה 23). פרטים נוספים זמינים במאמר בנושא טווח תאריכים.

דוגמאות לקוד

בספריות הלקוח יש דוגמאות לשימוש בשפת השאילתות של Google Ads‏ (GAQL) ב-GoogleAdsService. בתיקייה basic operations יש דוגמאות כמו GetCampaigns, GetKeywords ו-SearchForGoogleAdsFields.

הבא
דקדוק של שאילתות