המדריך למפתחים בנושא שפת השאילתות של בעלי תוכן דיגיטלי (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 מקביל לשאילתות רבות של =, אחת לכל ערך, שמאורגנות ביחד. הערכים מצוינים כרשימת ערכים שמופרדים בפסיקים ומוקפים בסוגריים: (a, b, c). כל הערכים ברשימה נבדקים.

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

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

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

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

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

  • IS NULL – מאפשרת להריץ שאילתות על אובייקטים עם ערך מאפיין לא מוגדר. הדוגמה הקלאסית לכך היא שאילתה לשורש 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='v202402')

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)

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

כדי להתאים את הדוח לנתונים נוספים של פריטים, אפשר להשתמש בטבלת 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)

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

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