מבנה השאילתה

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

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