מבנה השאילתה

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

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

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

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