מבנה השאילתות

אפשר לשלוח שאילתות לשדות של משאבים, פלחים ומדדים לשיטות Search או SearchStream של GoogleAdsService. כדי ליצור שאילתות בשפת השאילתות של Google Ads, צריך ליצור אותן לפי דקדוק השפה. שאילתות מורכבות מכמה תנאים:

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

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

משפטי משנה

סרטון: תאימות שדות של GAQL

‪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

יכול להיות ששדות מסוימים לא יהיו מותרים בפסקה SELECT בגלל המגבלות הבאות:

  • שליחת שאילתות לשדות שלא ניתן לבחור. מאפיין המטא-נתונים Selectable של השדות האלה יסומן כ-false.
  • בחירת מאפיינים של שדות חוזרים. מאפיין המטא-נתונים isRepeated של השדות האלה יסומן כ-true.
  • בחירת שדות שלא זמינים למשאב הנתון בפסקה FROM. אי אפשר לבחור יחד מאפיינים של משאבים מסוימים, ורק קבוצת משנה של כל המדדים והפלחים תהיה זמינה למשאב בפסקה FROM.
  • בחירת פלחים או מדדים שלא תואמים זה לזה. למידע נוסף, קראו את הקטע בנושא פילוח.

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

FROM

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

לדוגמה, אפשר להשתמש ב-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.

דוגמאות להגדרת omit_unselected_resource_names
SELECT
  campaign.name,
  customer.id
FROM campaign
 		Returned resources:
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
 		Returned resources:
ללא.
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
 		Returned resource:
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'
הקודם
דקדוק השאילתה
הבא
טווחי תאריכים