发布商查询语言 (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 - 联接多个条件，其中只有一个条件必须为真。如果您想查看单个 Pod 的多个值中的任何一个 属性，请考虑使用 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 - 可让您查询具有 未定义的属性值。一个典型的例子是，通过查询父 ID 为 null 的 AdUnit 来查询根 AdUnit。

  示例：WHERE parentId IS NULL

• <bind variable> - 您可以在 PQL 查询中使用 Value 对象来替换硬编码的 <value> 值。绑定 变量在 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='v202505')

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