发布商查询语言 (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 关键字不区分大小写。
  • 在绑定参数中使用时,字符串会自动转义。否则:
    • 对于使用单引号(撇号)的字符串,将任何其他撇号编写为一对单引号来对其进行转义。

      示例"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 - 用于连接多个条件(只有一个条件必须为 true)。如果您要查看单个属性的任何一个值,请考虑使用 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 查询。例如,您可以过滤的广告素材属性包括 idnamewidthheight
  • <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 - 可让您使用通配符字符串匹配查询对象。百分号 (%) 表示 0 个、1 个或多个字符。使用一对字符串将要匹配的搜索字符串括起来。

    示例WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL - 可让您查询具有未定义属性值的对象。一个典型示例是通过查询父 ID 为 null 的 AdUnit 来查询根 AdUnit

    示例WHERE parentId IS NULL

  • <bind variable> - 您可以在 PQL 查询中使用 Value 对象代替硬编码的 <value> 值。在 PQL 中,绑定变量使用不含空格、以冒号 (:) 开头的字符串名称命名。

    示例(创建一个查询,并输入两个变量来代替硬编码的 idstatus 属性值)

    // 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='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)

下载 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 上查看