发布商查询语言 (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 关键字不区分大小写。
• 在绑定参数中使用时，字符串会自动转义。否则： <ph type="x-smartling-placeholder">
  </ph>

  • 对于使用单引号（撇号）的字符串，请转义任意字符。 还可以添加额外的撇号。

    示例："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 - 将属性值与 列表；如果任一项匹配，则为肯定匹配。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 或 多个字符。使用 Pair 对来括住要匹配的搜索字符串。

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

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

  示例：WHERE parentId IS NULL

• <bind variable> - 您可以使用 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. 使用 <ph type="x-smartling-placeholder"></ph> 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='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 上查看