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

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

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

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

סעיפים

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

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

FROM

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

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

יש תמיכה בפרמטרים הבאים של meta:

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

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

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

כללים נוספים לגבי שפות

בנוסף לדוגמאות לכל סעיף, לשפת השאילתות של 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'