راهنمای توسعه دهنده زبان پرس و جو ناشر (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 به حروف بزرگ و کوچک حساس نیستند.
  • رشته ها هنگام استفاده در پارامترهای bind به طور خودکار فرار می کنند. در غیر این صورت:

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

      مثال: "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> - مقادیر رشته باید با یک علامت نقل قول (') نقل قول شوند. مقادیر اعداد می توانند نقل قول یا بدون نقل قول باشند. Wildcards پشتیبانی نمی شوند.
  • IN - ارزش یک ویژگی را با هر مورد در یک لیست مقایسه می کند. اگر کسی مطابقت داشته باشد، یک مسابقه مثبت است. عملگر IN معادل بسیاری = query است، یکی برای هر مقدار، که با هم 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 خود استفاده کنید. یک متغیر bind در 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 به یک متغیر bind یا با استفاده از رشته ای که بر اساس 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 ، بروید.

پایتون

یک درخواست گزارش تنظیم کنید

با ایجاد یک کار گزارش شروع کنید و پارامترهای گزارش خود را مانند ابعاد، ستون ها و محدوده تاریخ را مشخص کنید. 

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

داده های گزارش را با داده های مورد خط بپیوندید

این مثال از کتابخانه 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 مشاهده کنید