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

אפשר לשלוח שאילתות על שדות של משאבים, פלחים ומדדים לשיטות GoogleAdsService חיפוש או SearchStream. כדי ליצור שאילתה בשפת השאילתות של 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 חיפוש או 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 ו-segment.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.

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