אפשר לשלוח שאילתות לגבי שדות של משאבים, פלחים ומדדים לשיטות GoogleAdsService
Search או SearchStream. כדי ליצור שאילתה בשפת השאילתות של Google Ads, צריך להשתמש בדקדוק של השפה. שאילתה מורכבת ממספר סעיפים:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
סעיפים משתמשים בשמות שדות, בשמות משאבים, באופרטורים, בתנאים ובסדרים כדי לעזור לכם לבחור את הנתונים הנכונים. אפשר לשלב את השאילתות האלה לשאילתה אחת ולשלוח בקשה באמצעות Google Ads API.
סעיפים
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
.
omit_unselected_resource_names examples | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.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'