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

שפת השאילתות של Google Ads יכולה להריץ שאילתות ב-Google Ads API לגבי:

משאבים, המאפיינים, הפלחים והמדדים המשויכים להם באמצעות

GoogleAdsService Search או SearchStream

התוצאה של שאילתה של GoogleAdsService היא רשימה של מכונות GoogleAdsRow, כאשר כל מכונה מסוג GoogleAdsRow מייצגת משאב. אם מבקשים מאפיינים או מדדים, השורה כוללת גם את השדות האלה. אם מבקשים פלחים, התגובה כוללת גם שורה נוספת לכל קבוצה של שתי ערכים (tuple) של משאב-פלח.

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

GoogleAdsFieldService

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

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

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

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

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 שמתקבל מייצג קבוצה של קמפיין והתאריך Segment. חשוב לציין שהפילוח מפצל את המדדים שנבחרו, ומקבץ אותם לפי כל פלח בתנאי ה-SELECT.

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

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

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

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

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

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

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

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

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

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

שאילתות שנשלחות אל 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).

נקודת מפתח: שימו לב שאין תנאי FROM בשאילתה הזו.

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

דוגמאות לקוד

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