מבנה השאילתה

אפשר לשלוח שאילתות לגבי שדות של משאבים, פלחים ומדדים אל ה-method‏ GoogleAdsService Search או SearchStream. כדי ליצור שאילתה בשפת השאילתות של Google Ads, צריך להשתמש בדקדוק של השפה. לסקירה כללית על שפת השאילתות של Google Ads, אפשר לעיין בסקירה הכללית על שפת השאילתות של Google Ads. שאילתה מורכבת מכמה פסוקיות:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

הפסוקיות כוללות שמות של שדות, שמות של משאבים, אופרטורים, תנאים וסדרים, כדי לעזור לכם לבחור את הנתונים הנכונים. אחרי שמשלבים אותם לשאילתה אחת, אפשר לשלוח את הבקשה ל-Google Ads API.

סעיפים

בקטעים הבאים מתוארים המטרה והתחביר של כל פסוקית בשפת השאילתות של Google Ads.

‪SELECT

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

בדוגמה הבאה אפשר לראות איך בוחרים מאפיינים של משאב מסוים:

SELECT
  campaign.id,
  campaign.name
FROM campaign

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

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  • שדות המשאבים העיקריים
    • campaign.id
    • campaign.name
  • שדות של משאבים משויכים
    • bidding_strategy.id
    • bidding_strategy.name
  • שדות פילוח
    • segments.device
    • segments.date
  • מדדים
    • metrics.impressions
    • metrics.clicks
  • שליחת שאילתות לגבי שדות שלא ניתן לבחור. מאפיין המטא-נתונים selectable של השדות האלה מסומן כ-false.
  • בחירת מאפיינים של שדות חוזרים. מאפיין המטא-נתונים is_repeated של השדות האלה מסומן כ-true.
  • בחירת שדות שלא זמינים למשאב הנתון בסעיף FROM. אי אפשר לבחור יחד מאפיינים של חלק מהמשאבים, ורק קבוצת משנה של כל המדדים והפלחים זמינה למשאב בסעיף FROM.
  • בחירה בפלחים או במדדים שלא תואמים זה לזה. מידע נוסף זמין במאמר פילוח.

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

FROM

הסעיף FROM מציין את המשאב הראשי שיוחזר. המשאב בסעיף FROM מגדיר אילו שדות אפשר להשתמש בכל שאר הסעיפים בשאילתה הנתונה. אפשר לציין רק משאב אחד בסעיף FROM. הסעיף FROM הוא חובה בשאילתה ל-method‏ GoogleAdsService,‏ Search או SearchStream. עם זאת, כשמשתמשים ב-GoogleAdsFieldService, אסור לציין את הסעיף FROM.

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

השדה resource_name של המשאב הראשי תמיד מוחזר. בדוגמה הבאה, ad_group.resource_name נכלל בתגובה למרות שלא נבחר באופן מפורש בשאילתה:

SELECT ad_group.id
FROM ad_group

אותו עיקרון חל על משאבים משויכים כשבוחרים לפחות שדה אחד. לדוגמה, campaign.resource_name נכלל בתגובה לשאילתה הבאה:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

סעיף WHERE מציין תנאים להחלה כשמסננים נתונים לבקשה. כשמשתמשים בסעיף WHERE, צריך לציין תנאי אחד או יותר שמופרדים באמצעות AND. התנאים בדרך כלל פועלים לפי התבנית field_name Operator value (או משתמשים ב-BETWEEN value AND value, ב-IS NULL או ב-IS NOT NULL). הסעיף WHERE הוא אופציונלי בשאילתה.

בדוגמה הבאה משתמשים ב-WHERE כדי להחזיר מדדים מתקופה נתונה:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

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

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = 'MOBILE'
  AND segments.date DURING LAST_30_DAYS

פלחים בסעיף WHERE חייבים להופיע גם בסעיף SELECT, חוץ מפלחים מבוססי-זמן, שנקראים פלחים יסודיים מבוססי-זמן:

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

בשאילתה הבאה, נבחר segments.date. הפלח הזה הוא פלח יסודי מבוסס-זמן, ולכן צריך לציין טווח תאריכים סופי בסעיף WHERE שמורכב מפלחים יסודיים מבוססי-זמן:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

כל הפלחים שעומדים בתנאי הקודם הם segments.date,‏ segments.week,‏ segments.month,‏ segments.quarter ו-segments.year. אם בוחרים אחד מהפלחים האלה, צריך להשתמש לפחות באחד מהם בסעיף WHERE.

פרטים נוספים על סינון לפי תאריך זמינים במאמר בנושא טווח תאריכים.

כשמסננים, חשוב לזכור אם האופרטור תלוי אותיות רישיות (case-sensitive). מידע נוסף זמין במאמר תלוי אותיות רישיות.

לרשימה המלאה של האופרטורים, עיינו בדקדוק השפה.

ORDER BY

הסעיף ORDER BY מציין את הסדר שבו התוצאות מוחזרות. כך אפשר לסדר את הנתונים בסדר עולה או יורד לפי שם השדה. כל סדר מוגדר כ-field_name ואחריו ASC או DESC. אם לא מציינים את ASC או את DESC, ברירת המחדל היא ASC. הפסקה ORDER BY היא אופציונלית בשאילתה.

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

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

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

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

הגבלה

הסעיף LIMIT מאפשר לציין את מספר התוצאות שיוחזרו. האפשרות הזו שימושית אם אתם צריכים רק קבוצת משנה של תוצאות.

לדוגמה, LIMIT יכול להגביל את מספר התוצאות הכולל של השאילתה הבאה:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

פרמטרים

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

אפשר להשתמש בפרמטרים הבאים של מטא-נתונים:

include_drafts

מגדירים את include_drafts לערך true כדי להחזיר ישויות של טיוטות. ברירת המחדל היא false.

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

מגדירים את omit_unselected_resource_names לערך true כדי להשמיט את שם המשאב של כל סוג משאב בתגובה, אלא אם ביקשתם אותו במפורש בסעיף SELECT. ברירת המחדל היא false.

שאילתה המשאבים שהוחזרו 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

ערך ברירת המחדל של omit_unselected_resource_names הוא false, ולכן כל השדות של resource_name מוחזרים.

 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

ללא

‫omit_unselected_resource_names מוגדר כ-true, ואף אחד מהערכים campaign.resource_name או customer.resource_name לא נכלל בסעיף SELECT.

 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
  • campaign.resource_name

הערך של omit_unselected_resource_names הוא true, והערך של campaign.resource_name נכלל בבקשה כחלק מהסעיף SELECT.

כללי שפה נוספים

בנוסף לדוגמאות לכל פסוקית, שפת השאילתות של Google Ads תומכת בהתנהגויות הבאות:

  • לא חובה להוסיף את שדה המשאב הראשי בסעיף SELECT של השאילתה. לדוגמה, אתם יכולים להשתמש בשדה אחד או יותר של משאב ראשי כדי לסנן נתונים בלי לבחור אותם:

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = 'PAUSED'

  • אפשר לבחור מדדים באופן בלעדי למשאב נתון, ואין צורך בשדות אחרים מהמשאב בשאילתה:

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • אפשר לבחור שדות פילוח בלי שדות משאבים או מדדים נלווים:

    SELECT segments.device FROM campaign

  • אפשר להשתמש בשדה resource_name (לדוגמה, campaign.resource_name) כדי לסנן או לסדר את הנתונים:

    SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
הקודם
דקדוק של שאילתות
הבא
טווחי תאריכים