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

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

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

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

סעיפים

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

בחירה

הסעיף SELECT מציין קבוצת שדות לאחזור בבקשה. SELECT לוקחת רשימה מופרדת בפסיקים של שדות משאבים, שדות פילוח, ומדדים, מחזירים את הערכים בתשובה. הסעיף SELECT הוא חובה בשאילתה.

השאילתה לדוגמה שלמטה מציגה דוגמה לבחירת מאפיינים עבור נתון resource:

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