המבנה והסעיפים של השאילתות

שאילתה מורכבת ממספר פסוקיות: SELECT, FROM, WHERE, ORDER BY, LIMIT ו- PARAMETERS.

סעיפים משתמשים בשמות שדות, שמות משאבים, אופרטורים, תנאים וסדרים שמשולבים בבקשת שאילתה אחת.

במילים פשוטות, כדי ליצור שאילתה:

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

SELECT סעיף

הסעיף SELECT:

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

בדוגמת השאילתה הזו אפשר לראות איך בוחרים מאפיינים של campaign resource:

SELECT
  campaign.id,
  campaign.name
FROM campaign

כמה סוגי שדות

אפשר לבקש סוגים שונים של שדות באותה בקשה.

בדוגמה הבאה מוצגת שאילתה יחידה עם שילוב של:

• שדות של משאבים: campaign.id,‏ campaign.name,‏ bidding_strategy.id ו-bidding_strategy.name.

• שדות פלחים: segments.device ו-segments.date.

• שדות מדדים: metrics.impressions ו-metrics.clicks.

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

במאמר בנושא פילוח מוסבר איך לפלח את דוחות החיפוש.

שדה המשאב הראשי

בדרך כלל, כוללים את שדה המשאב הראשי בסעיף SELECT, אבל זה אופציונלי (לא חובה).

בדוגמה הזו של שאילתה נעשה שימוש בשדה של משאב ראשי (ad_group.status) כדי לסנן רק את התוצאות.

SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

משתנים מותאמים אישית ב-Floodlight

אפשר לכלול משתנים מותאמים אישית ב-Floodlight בסעיף SELECT באמצעות המזהים שלהם.

בדוגמה הזו, השאילתה כוללת משתנה מותאם אישית עם המזהה 123454321 עבור משאב הקמפיין.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

עמודות בהתאמה אישית

אפשר לכלול עמודות בהתאמה אישית במשפט SELECT באמצעות המזהים שלהן.

בדוגמה הזו, השאילתה כוללת עמודה בהתאמה אישית עם מזהה 12345678 עבור משאב הקמפיין.

SELECT
  custom_columns.id[12345678]
FROM campaign

איך מקבלים מזהים של עמודות בהתאמה אישית

שדות של מדדים

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

בדוגמה הזו של שאילתה נבחרו המדדים impressions ו-clicks עבור המשאב campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

metrics אפשר לעיין ברשימה של שדות המדדים שאפשר להשתמש בהם בשאילתות.

שדות של פלחים

אפשר לבחור שדות של פלחים בלי לציין שדות משאבים או מדדים נלווים בסעיף SELECT.

בדוגמה הזו, השאילתה מפלח את התוצאות לפי מכשיר.

SELECT segments.device
FROM campaign

segments מופיעה רשימה של שדות פלחים שאפשר להשתמש בהם בשאילתות.

שדות אסורים

אי אפשר להשתמש בשדות הבאים בסעיף SELECT:

• שדות שלא ניתן לבחור, כלומר שדות עם מאפיין המטא-נתונים Selectable false.

• שדות חוזרים, כלומר שדות עם מאפיין המטא-נתונים Repeated שמסומן כ-true.

• שדות שלא זמינים למשאב הנתון בסעיף FROM. אי אפשר לבחור יחד מאפיינים של חלק מהמשאבים. חלק מהמשאבים מאפשרים גישה רק לקבוצת משנה של כל המדדים והפלחים.

• פלחים או מדדים לא תואמים. מידע נוסף זמין במאמר בנושא פילוח.

במאמרי העזרה מוסבר איפה אפשר למצוא את המידע הזה לכל משאב.

פסוקית FROM

הסעיף FROM:

• היא סעיף חובה בשאילתות אל SearchAds360Service (גם בשיטות Search וגם בשיטות SearchStream).

• האם לא צריך להיכלל בשאילתות אל SearchAds360FieldService.

• מציין את המשאב הראשי שהשאילתה מחזירה.

• אפשר לציין רק משאב אחד.

• התנאי הזה מגדיר את השדות שאפשר להשתמש בהם בכל שאר הסעיפים בשאילתה.

הערה: בכל דף משאב בקטע Reference יש שדה בחירה עם האפשרויות Yes/No. השדה הזה מסנן שדות של משאבים, שדות של פלחים ושדות של מדדים שלא ניתן להשתמש בהם כשמציינים משאב בסעיף FROM.

משאבים עם ייחוס

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

שאילתת הדוגמה הזו מחזירה גם את מזהה קבוצת המודעות וגם את מזהה הקמפיין, כי campaign הוא משאב משויך של המשאב ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

הערה: לא לכל המשאבים יש משאבים משויכים. בקטע הפניה מפורטים המשאבים המשויכים שזמינים לכל משאב.

שדה resource_name

השדה resource_name של המשאב הראשי בסעיף FROM תמיד מוחזר.

בדוגמה הזו של שאילתה, התוצאה ad_group.resource_name תיכלל בתשובה, גם אם היא לא נבחרה במפורש בשאילתה:

SELECT ad_group.id
FROM ad_group

השדה resource_name של משאב משויך מוחזר כשבוחרים לפחות שדה אחד.

בדוגמה הזו של שאילתה, campaign.resource_name ייכלל בתשובה כי campaign.id נבחר:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

הערה: אם במשאב שבסעיף FROM מופיע משאב אחר בתור segment, בחירה של מאפיינים כלשהם של המשאב הזה פועלת כמו פילוח.

פסוקית WHERE

הסעיף WHERE:

• הוא סעיף אופציונלי בשאילתה.

• מציין תנאים לסינון ולפילוח של הנתונים בבקשה. התנאים פועלים לפי הדפוס הבא: FIELD_NAME OPERATOR VALUE (מופרדים על ידי רווחים).

• אפשר לכלול כמה תנאים שמופרדים באמצעות המפריד AND.

השאילתה לדוגמה הזו מראה איך להשתמש בסעיף WHERE כדי להחזיר מדדים של impressions לתקופה נתונה:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

במאמר בנושא פילוח מוסבר איך לפלח את דוחות החיפוש.

במאמר טווחי תאריכים מוסבר איך מציינים טווחי תאריכים בשאילתות.

סינון לפי שדה resource_name

אפשר להשתמש בשדה resource_name כדי לסנן או לסדר את הנתונים.

בדוגמה הבאה של שאילתה נעשה שימוש בשדה campaign.resource_name כדי לסנן את התוצאות לפי קמפיין נתון:

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

כמה תנאים

אפשר לשלב כמה תנאים כדי לסנן את הנתונים.

בשאילתה לדוגמה הזו מתבקש מספר המדדים clicks לכל הקמפיינים עם מדדים impressions בנייד ב-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

הערה: אפשר להשתמש במפריד AND רק בין תנאי אופרטורים (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), ולא בתוך תנאי אופרטור יחיד (WHERE segments.device != "DESKTOP" AND "MOBILE").

במאמר פילוח מוסבר איך לפלח את הדוחות.

תלות באותיות רישיות (Case sensitivity)

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

בטבלה הבאה מוצגת רגישות האותיות הרישיות של כל אופרטור כברירת מחדל.

ברירת מחדל של תלות באותיות רישיות
=/!=	Case sensitive
IN/NOT IN	Case sensitive
LIKE/NOT LIKE	Case insensitive
CONTAINS (...)	Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH	Case sensitive

אפשר להשתמש בשינוי (?i) כדי לשנות את רגישות ברירת המחדל של REGEXP_MATCH ושל NOT REGEXP_MATCH כך שלא תהיה רגישות לאותיות רישיות, לדוגמה:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

כאן אפשר לראות רשימה מלאה של אופרטורים שאפשר להשתמש בהם כדי לסנן את הנתונים.

פילוחי נתונים מרכזיים

השדות הבאים של פלחים נקראים פלחים של נתוני ליבה: segments.date,‏ segments.week,‏ segments.month,‏ segments.quarter ו-segments.year.

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

בדוגמה הזו של שאילתה, הערך DURING LAST_30_DAYS מוגדר לשדה segments.date בסעיף WHERE:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

בקטע פילוח > פלחי תאריכים מרכזיים אפשר לקרוא מידע מפורט על שימוש בפלחי תאריכים מרכזיים.

סינון אסור

אסור להשתמש בסינון:

• בשדות של פלחים שלא נבחרו, למעט פלחי תאריכים מרכזיים.

• בשדות של כל סוג הודעה, חוץ מפרימיטיבים (למשל, Int64Value, StringValue וכו').

• במאפיינים של שדות חוזרים מכל סוג הודעה, למעט פרימיטיבים (לדוגמה, Int64Value,‏ StringValue וכו').

סעיף ORDER BY

הסעיף ORDER BY:

• הוא סעיף אופציונלי בשאילתה.
• מציין את הסדר שבו התוצאות מוחזרות. ההזמנה מתבצעת לפי התבנית הבאה: FIELD_NAME ORDERING_OPTION (מופרדים ברווח).
• אפשר לבחור באחת משתי האפשרויות: ASC (סדר עולה) או DESC (סדר יורד). ברירת המחדל היא סדר עולה.

בדוגמה הזו, השאילתה ממיינת את הקמפיינים לפי מספר הקליקים בסדר יורד (מהגבוה לנמוך):

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

שילוב של סדר והגבלה

אפשר להשתמש בסעיף ORDER BY בשילוב עם הסעיף LIMIT כדי לדייק את התוצאות.

השאילתה לדוגמה הזו מחזירה את חמשת הקמפיינים עם מספר החשיפות הגבוה ביותר ב-30 הימים האחרונים:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

הזמנה אסורה

אסור לפרסם:

• לפי מאפיינים של משאבים שלא נבחרו.
• לפי מדדים שלא נבחרו.
• לפי פלחים שלא נבחרו.
• לסוגי השדות האלה:
  • MESSAGE
  • שדות חוזרים
  • מאפיינים של שדות חוזרים.

סעיף הגבלה

הסעיף LIMIT:

• הוא סעיף אופציונלי בשאילתה.
• מאפשר להגביל את מספר התוצאות שהשאילתה מחזירה.

הסעיף הזה שימושי, למשל, אם אתם מעוניינים רק בדוגמה או בסיכום של התוצאות.

בדוגמה הזו, השאילתה מגבילה את המספר הכולל של התוצאות ל-50:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

סעיף PARAMETERS

הפסקה PARAMETERS מאפשרת לציין פרמטרים של מטא לכל בקשה.

הכללת טיוטות

הפרמטר include_drafts קובע אם ישויות בטיוטה ייכללו בתוצאות. ערך ברירת המחדל הוא false. כדי לכלול ישויות בטיוטה, צריך להגדיר את הערך ל-true.

השאילתה לדוגמה הזו מחזירה גם טיוטות של קמפיינים וגם קמפיינים רגילים:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

השמטת פריטים לא מסומנים resource_name

הפרמטר omit_unselected_resource_names מאפשר לכם להחריג את השדה resource_name של כל המשאבים שלא נדרשו במפורש בסעיף SELECT. ערך ברירת המחדל הוא false. אם מגדירים את הפרמטר הזה לערך true, מומלץ לבקש במפורש את שם המשאב של המשאב הראשי ושל כל משאב משויך בסעיף SELECT.

השאילתה לדוגמה הזו לא מחזירה את השדה campaign.resource_name ולא את השדה customer.resource_name, כי הם לא נכללים בסעיף SELECT:

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

השאילתה בדוגמה הזו מחזירה את השדה campaign.resource_name, כי הוא נכלל באופן מפורש בסעיף SELECT:

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

שינוי המטבע שמוצג במדדים

הפרמטר metrics_currency מאפשר לציין את המטבע שבו יש להשתמש כשמחשבים מדד שכלול בסעיף SELECT. ברירת המחדל היא שימוש במטבע של החשבון שצוין על ידי customer_id. אם מגדירים את הפרמטר הזה, צריך להשתמש בקוד מטבע בן 3 אותיות בתקן ISO 4217. לדוגמה: USD, EUR.

בדוגמה הזו, השאילתה מחזירה את מדד העלות (cost_micros) במטבע של החשבון שצוין על ידי customer_id.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

בדוגמת השאילתה הזו, המדד cost_micros מוחזר בפסו צ'יליאני (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

הפעלת הרחבת חשבון ניהול

הפרמטר enable_mcc_expansion, כשהוא מוגדר כ-true, מאפשר לכם לכלול מדדים, שדות ופלחים מכל החשבונות שמושרשים ב-customer_id, עבור המשאב בסעיף FROM. המערכת תציין את ערך ההמרה במטבע של customer_id, אלא אם תציינו במפורש מטבע אחר בפרמטר metrics_currency.

הערה: הפרמטר enable_mcc_expansion תואם רק ל-bidding_strategy. ה-API יכלול משאבים נוספים בהמשך.

שאילתת הדוגמה הזו מחזירה את הערכים bidding_strategy.name, bidding_strategy.type ו-metrics.cost_micros מכל החשבונות בהיררכיית החשבונות ששורש שלה הוא customer_id, כי הפרמטר enable_mcc_expansion מוגדר לערך true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

מידע נוסף

• תחביר של שאילתות