راهنمای توسعه‌دهنده Publisher Query Language (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>

مهم: ReportService فقط از زیرمجموعه‌ای از نحو PQL پشتیبانی می‌کند. برای جزئیات، به اسناد ReportQuery مراجعه کنید.

یادداشت‌ها

• کلیدواژه‌های PQL به حروف بزرگ و کوچک حساس نیستند.
• رشته‌ها هنگام استفاده در پارامترهای اتصال به‌طور خودکار گریز داده می‌شوند. درغیراین‌صورت:

  • برای رشته‌ای که در گیومه تکی (آپاستروف) قرار دارد، هر آپاستروف اضافی را با نوشتن آن به‌صورت یک جفت گیومه تکی گریز دهید.

    مثال: "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 - افست در مجموعه نتایج برای شروع برگرداندن مقادیر. از این گزینه برای ورق زدن نتایج استفاده کنید.

  مثال (نتایج ۵۱ تا ۱۰۰ را برمی‌گرداند):
  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 - به شما امکان می‌دهد اشیایی را که مقدار ویژگی تعریف‌نشده دارند جستجو کنید. نمونه کلاسیک این مورد، پرسمان برای ریشه AdUnit با پرسمان برای AdUnit با شناسه ولی تهی است.

  مثال: 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 Data Transfer Service استفاده کنید. توجه داشته باشید که این جدول‌های مطابقت شامل همه فیلدهای نهاد نیستند.
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='v202608')

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