מבנה השאילתה

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

  • 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. עם זאת, לא צריך לציין את הסעיף FROM כשמשתמשים ב-GoogleAdsFieldService.

אפשר להוסיף רק משאב אחד לסעיף 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.

למידע נוסף על סינון לפי תאריך, ראו טווחי תאריכים.

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

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

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'
הקודם
דקדוק של שאילתות
הבא
טווחי תאריכים