המדריך למפתחים בנושא שפת השאילתות של בעלי תוכן דיגיטלי (PQL)

תחביר PQL ושימוש בהם

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

אפשר לסכם את התחביר של PQL באופן הבא:

[WHERE <condition> {[AND | OR] <condition> ...}]
[ORDER BY <property> [ASC | DESC]]
[LIMIT {[<offset>,] <count>} | {<count> OFFSET <offset>}]

<condition> := <property> { = | != } <value>
<condition> := <property> { = | != } <bind variable>
<condition> := <property> IN <list>
<condition> := NOT <property> IN <list>
<condition> := <property> LIKE <wildcard%match>
<condition> := <property> IS NULL
<bind variable> := :<name>

הערות

  • מילות המפתח ב-PQL לא תלויות אותיות רישיות.
  • מחרוזות מקבלות בריחה באופן אוטומטי כשמשתמשים בהן בפרמטרים של קישור. אחרת:

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

      לדוגמה: "WHERE name = 'Company''s name'"

מילות מפתח (לא תלויי-רישיות)

  • WHERE - מבטא קבוצה של אפס תנאים או יותר, אפשר להצטרף אליהן באמצעות ביטויי AND או OR. אפשר לקבץ ביטויים של AND או OR בסוגריים. מפעיל את השאילתה "" (ריק) ) מחזירה את כל הנתונים.

    דוגמאות: WHERE width = 728
    WHERE width = 728 AND height = 90
    WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

  • OR – מחברת בין מספר תנאים, שרק אחד מהם חייב להיות נכון. אם רוצים לבדוק אם נכס מסוים מכיל אחד מכמה ערכים, כדאי להשתמש בתנאי IN.

    לדוגמה: WHERE width = 728 OR height = 90

  • AND – מצרף כמה תנאים שחייבים להתקיים באמצעות תנאי AND.

    לדוגמה: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')

  • ORDER BY - מיון התוצאות שהוחזרו לפי בסדר עולה (ASC כאשר 'A' הוא ראשון) או בסדר יורד (DESC כאשר 'A' הוא האחרון). אם לא צוין כיוון, הערך שמוגדר כברירת מחדל הוא ASC. אם התנאי הזה לא נכלל, ברירת המחדל היא ASC בשדה הראשון.

    דוגמה: WHERE id IN (5008, 8745, 3487) ORDER BY id

  • LIMIT – מספר התוצאות שיש להחזיר. השדה LIMIT יכול לכלול גם את השדה <offset>, שמציין כמה שורות מההתחלה צריך להזיז את קבוצת התוצאות.

    דוגמאות (שתי הדוגמאות מחזירות את אותה קבוצת תוצאות):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET – הסטייה (סטייה) מהתוצאה שמתקבלת מחזירים נתונים. אפשר להשתמש במדד הזה כדי לעבור בין תוצאות.

    דוגמה (החזרת תוצאות 51-100):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property> – אחד מהמאפיינים שנחשפים על ידי האובייקט. כל אובייקט חושף מאפיינים שונים שניתן לסנן לפיהם, שימוש ב-PQL; בדרך כלל אי אפשר לסנן את כל המאפיינים שנתמכים על ידי לכן צריך לבדוק ברשימה הבאה אילו מאפיינים תומכים בשאילתות PQL. לדוגמה, מאפייני הקריאייטיב שאפשר לסנן לפיהם כוללים את id,‏ name,‏ width ו-height.
  • <value> – יש להקיף את ערכי המחרוזת במירכאות כפולות גרש יחיד ('). אפשר להקיף את ערכי המספרים במירכאות או ללא מירכאות. תווים כלליים לחיפוש אין תמיכה.
  • IN – השוואת הערך של מאפיין לכל פריט ברשימה. אם יש התאמה לפריט כלשהו, זוהי התאמה חיובית. IN שווה ערך להרבה שאילתות =, אחת לכל ערך, שמופרדים באמצעות OR. הערכים מצוינים כרשימה של ערכים מופרדים בפסיקים, בתוך סוגריים: (a, b, c). כל הערכים ברשימה עוד לא בדקתם.

    לדוגמה: WHERE name IN ('CompanyNameA', 'CompanyNameB')

  • NOT IN – השוואה בין ערך של נכס לכל פריט ברשימה; אם אין התאמה, מדובר בהתאמה חיובית. NOT IN שווה ערך להרבה שאילתות !=, אחת לכל ערך, שמופרדים באמצעות OR. הערכים מצוינים כרשימה של ערכים מופרדים בפסיקים, בתוך סוגריים: (a, b, c). כל הערכים ברשימה נבדקים.

    דוגמה: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

  • LIKE – מאפשר להריץ שאילתות לגבי אובייקטים באמצעות התאמה של מחרוזות עם תווים כלליים לחיפוש. סימן האחוז (%) מייצג את הערך אפס, אחד, או תווים מרובים. משתמשים בזוג כדי לתחום את מחרוזת החיפוש שמותאמת.

    דוגמאות: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL – מאפשרת להריץ שאילתות לאובייקטים עם ערך מאפיין לא מוגדר. הדוגמה הקלאסית היא שליחת שאילתה לגבי הרמה הבסיסית (root) AdUnit על ידי שליחת שאילתה ל-AdUnit עם ערך null מזהה הורה.

    דוגמה: WHERE parentId IS NULL.

  • <bind variable> – אפשר להשתמש ב-Value אובייקטים במקום <value> בתוך הקוד בשאילתת ה-PQL. הפניה למשתנה קישור ב-PQL מתבצעת באמצעות שם מחרוזת ללא רווחים, שמתחיל בנקודתיים (:).

    דוגמה (יצירת שאילתה והזנה של שני משתנים במקום ערכי המאפיינים id ו-status שמוגדרים בקוד):

    // Create two mapped parameters: id and status
String_ValueMapEntry[] values = new String_ValueMapEntry[2];
values[0] = new String_ValueMapEntry("id", new NumberValue(null, "123"));
values[1] = new String_ValueMapEntry("status", new TextValue(null, "APPROVED"));

// Create our statement and map our bind variables
Statement statement = new Statement();
statement.setQuery("WHERE id = :id AND status = :status LIMIT 500");
statement.setValues(values);
  • שדות DateTime – אפשר לסנן לפי תאריך ושעה על ידי הקצאת ערך DateTime למשתנה קישור, או באמצעות מחרוזת בפורמט ISO 8601. 
    // Create a bind variable: startDateTime
String_ValueMapEntry[] values = new String_ValueMapEntry[1];
values[0] = new String_ValueMapEntry("startDateTime", new DateTimeValue(null, dateTime));

// Create our statement and map our bind variables
Statement statement = new Statement();
statement.setQuery("WHERE endDateTime < '2019-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500");
statement.setValues(values);

אחזור טבלאות של התאמות באמצעות PQL

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

אם אתם מריצים דוחות באמצעות ReportService או עם העברת נתונים , מומלץ להוסיף לנתוני הדוחות . לדוגמה, עם דוח שמכיל את המאפיין LINE_ITEM_ID או באמצעות אירוע העברת נתונים שמכיל את השדה LineItemId, אפשר ליצור טבלת התאמות שכוללת את תאריך ההתחלה של כל פריט, תאריך סיום, סוג, סטטוס ומאפיינים שימושיים אחרים.

יש כמה דרכים להשיג את התאמת הנתונים הזו:

  1. להשתמש בטבלאות ההתאמה המוגדרות מראש שסופקו על ידי שירות העברת הנתונים ל-BigQuery. שימו לב שטבלאות ההתאמה האלה לא מכילות את כל השדות של הישויות.
  2. גישה יעילה היא להשתמש באחת מהטבלאות של PublisherQueryLanguageService.
  3. אם אין טבלת BigQuery או PQL של הישות, או אם בטבלה חסרים שדות שאתם צריכים, תוכלו להשתמש ישירות בשירות של הישות, למשל OrderService.

Python

הגדרת שאילתת דוח

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

# Set the start and end dates of the report to run (past 8 days).
end_date = date.today()
start_date = end_date - timedelta(days=8)

# Create report job.
report_job = {
    'reportQuery': {
        'dimensions': ['LINE_ITEM_ID', 'LINE_ITEM_NAME'],
        'columns': ['AD_SERVER_IMPRESSIONS', 'AD_SERVER_CLICKS',
                    'AD_SERVER_CTR', 'AD_SERVER_CPM_AND_CPC_REVENUE',
                    'AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM'],
        'dateRangeType': 'CUSTOM_DATE',
        'startDate': start_date,
        'endDate': end_date
    }
}

הורדת הדוח

# Initialize a DataDownloader.
report_downloader = client.GetDataDownloader(version='v202508')

try:
  # Run the report and wait for it to finish.
  report_job_id = report_downloader.WaitForReport(report_job)
except errors.AdManagerReportError as e:
  print('Failed to generate report. Error was: %s' % e)

with tempfile.NamedTemporaryFile(
    suffix='.csv.gz', mode='wb', delete=False) as report_file:
  # Download report data.
  report_downloader.DownloadReportToFile(
      report_job_id, 'CSV_DUMP', report_file)

הורדת נתונים מהטבלה Line_Item PQL

כדי להתאים את הדוח לנתונים נוספים של פריטי שורה, אפשר להשתמש בטבלת PQL‏ Line_Item.

# Create a PQL query to fetch the line item data
line_items_pql_query = ('SELECT Id, LineItemType, Status FROM LineItem')

# Download the response from PQL select statement
line_items = report_downloader.DownloadPqlResultToList(line_items_pql_query)

איך משלבים נתוני דוחות עם נתוני פריטים

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

# Use pandas to join the two csv files into a match table
report = pandas.read_csv(report_file.name)
line_items = pandas.DataFrame(data=line_items[1:], columns=line_items[0])
merged_result = pandas.merge(report, line_items,
                             left_on='Dimension.LINE_ITEM_ID', right_on='id')
merged_result.to_csv('~/complete_line_items_report.csv', index=False)
 הצגה ב-GitHub