שפת השאילתות של 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.

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

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

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 כדי לבדוק את התאימות של השדות ואת סוגי הנתונים לפני שיוצרים שאילתות מורכבות.
  • חשוב לזכור ששדות מסוימים, במיוחד כאלה שכוללים כמויות גדולות של נתונים או חישובים מורכבים, יכולים להגדיל את עלות השאילתה.

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

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

  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 ו-v26), אבל קטלוג המשאבים, הפלחים, המדדים והתנהגויות הדיווח שניתן לשלוח לגביהם שאילתות שונה בכל גרסה ראשית. שולחים שאילתה ל-GoogleAdsFieldService בנקודת הקצה של גרסת ה-API לטירגוט כדי לבדוק את השדות ואת כללי התאימות של הגרסה הזו:

  • תצוגת הנכסים של התאמת כתובת URL סופית:
    • תמיכה בקמפיינים של שופינג (גרסה 26 ואילך): final_url_expansion_asset_view תומך בקמפיינים של שופינג (campaign.advertising_channel_type = 'SHOPPING') בנוסף לקמפיינים למיקסום הביצועים ולקמפיינים לרשת החיפוש. בקמפיינים של שופינג, אפשר לבחור ולסנן לפי שדות מסוג ad_group, אבל אי אפשר לבחור שדות מסוג asset_group.
    • מדדים שאפשר לבחור (גרסה 25 ואילך): שליחת שאילתה ל-final_url_expansion_asset_view מחזירה את כל המדדים שאפשר לבחור בתצוגה. בגרסה 24 ובגרסאות קודמות, התגובות כוללות רק את metrics.conversions ו-metrics.conversions_value בקמפיינים למיקסום הביצועים, ואת metrics.impressions בקמפיינים לרשת החיפוש.
  • משאבים של יעדים שקשורים למחזור החיים של הלקוח: בגרסה 25 ואילך, כל היעדים שקשורים למחזור החיים של הלקוח (היעד "צירוף לקוחות חדשים", שימור לקוחות ושימור לקוחות נאמנים) נשלפים מהמשאבים המאוחדים goal ו-campaign_goal_config, שמחליפים את customer_lifecycle_goal ו-campaign_lifecycle_goal (ששימשו ליעדים של צירוף לקוחות חדשים בגרסה 24 ובגרסאות קודמות, לצד goal ו-campaign_goal_config ליעדים של שימור לקוחות).
  • דיווח על מוצרי שופינג בקמפיינים לקידום אפליקציות: בגרסה 24 ואילך, המשאב shopping_product מחזיר שורות של מוצרים בקמפיינים לקידום אפליקציות, בנוסף לקמפיינים של שופינג, קמפיינים למיקסום ביצועים, קמפיינים ליצירת ביקוש וקמפיינים של מודעות וידאו (בגרסה 23, קמפיינים לקידום אפליקציות לא נכללים בתוצאות של shopping_product).
  • משאבים, פלחים ומדדים ספציפיים לגרסה:
    • ‫גרסה 26 ואילך: כוללת את המשאב search_lift_keyword_bundle, את campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property ואת מדדי העלייה בנפח החיפוש (כמו metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros ו-metrics.search_lift_impressions).
    • גרסה 25 ואילך: כוללת משאבים למדידת התחזקות המותג (כמו 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 (שאפשר לבחור בגרסה 24 ובגרסאות קודמות).
    • גרסה 24 ואילך: כוללת את המשאב 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 ב-GoogleAdsService. בתיקייה basic operations יש דוגמאות כמו GetCampaigns,‏ GetKeywords ו-SearchForGoogleAdsFields.

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