Reminder: v201702 will be sunset on February 28, 2018.

发布商查询语言 (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 - 可让您使用部分和通配符字符串匹配查询对象。

    示例WHERE name LIKE 'startswith%'

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

    示例WHERE parentId IS NULL

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

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

    // 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 two mapped parameters: id and status
    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 < '2012-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500");
    statement.setValues(values);

利用 PQL 提取匹配表

您可以使用匹配表来查找数据传输文件中包含的原始值,将广告投放信息(例如广告单元或订单项)与存储在数据库中的预分配值进行匹配。

如果您是通过 ReportService数据传输报表运行报表,则可能需要使用其他字段补充报表数据。例如,对于包含 LINE_ITEM_ID 维度的报表或包含 LineItemId 字段的数据传输事件,您可以创建一个匹配表,其中包含每个订单项的开始日期、结束日期、类型、状态和其他有用的属性。

您可以通过以下方式实现这种匹配功能:

  1. 有效的方法是使用任一可用的 PublisherQueryLanguageService 表格
  2. 如果您的客户端库支持,您可以使用内置的实用程序函数访问 PQL 表格,如下面的 Python 示例所示。
  3. 如果您所需的实体没有任何 PQL 表格,您可以直接经由该实体的服务(例如 OrderService)进行处理。

Python


  1. 设置报表查询

    首先创建一个报表作业,并指定报表参数(例如维度、列和日期范围)。

    # 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
        }
    }
        
  2. 下载报表
    # Initialize a DataDownloader.
    report_downloader = client.GetDataDownloader(version='v201708')
    
    try:
      # Run the report and wait for it to finish.
      report_job_id = report_downloader.WaitForReport(report_job)
    except errors.DfpReportError, 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)
        
  3. 下载 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)
        
  4. 将报表数据与订单项数据合并在一起

    此示例使用 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)
        

发送以下问题的反馈:

此网页
DoubleClick for Publishers
DoubleClick for Publishers
需要帮助?请访问我们的支持页面