המדריך למפתחים בנושא שפת השאילתות של בעלי תוכן דיגיטלי (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 לא תלויות אותיות רישיות (case-sensitive).
כשמשתמשים בפרמטרים של קישור, המערכת תסמן בתו מילוט (escape) באופן אוטומטי. אחרת:
- למחרוזת בתוך מירכאות בודדות (גרשיים), צריך לסמן בתו בריחה (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 – השוואת הערך של נכס לכל פריט list; אם מצאנו התאמה, מדובר בהתאמה חיובית. 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, אפשר ליצור טבלת התאמות שכוללת את תאריך ההתחלה של כל פריט, תאריך סיום, סוג, סטטוס ומאפיינים שימושיים אחרים.

יש כמה דרכים לקבל את הפונקציונליות התואמת הזו:

להשתמש בטבלאות התאמות מוכנות מראש שסופקו על ידי שירות העברת נתונים ל-BigQuery. שימו לב שטבלאות ההתאמה האלה לא מכילות את כל השדות של הישויות.
גישה יעילה היא להשתמש בכל אחד מהכלים הזמינים של PublisherQueryLanguageService טבלאות.
אם אין לישות טבלת 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='v202408')

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

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

# 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)

איחוד נתוני הדוח עם נתוני פריטים

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