发布商查询语言 (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 提取匹配表

匹配表可以对数据传输文件中包含的原始值进行名称和 ID 匹配查找,从而将广告投放信息(例如广告单元或订单项)与存储在数据库中的预先指定的值相匹配。例如,数据传输事件可能会记录于 01-6-2011 16:10:10 投放 ID 为 12345678 的订单项。通过订单项匹配表,您可以知道该订单项的名称及其开始日期、结束日期以及其他实用属性。

您可以使用 DFP API 轻松创建只包含您需要的字段和对象范围的匹配表脚本。可通过下方的链接找到一组 Python 匹配表脚本示例。此外,每个 DFP API 客户端库均包含各项服务的 GetAllX 示例。如果您使用的不是 Python,则可以调整这些 GetAllX 示例以将其输出到文件或数据库中,从而创建所需的匹配表脚本。

Python


  1. 设置凭据

    填充 googleads.yaml 文件中的模板化字段,然后调用 DfpClient.LoadFromStorage(),以初始化 Client 对象。

      # Initialize client object.
      dfp_client = dfp.DfpClient.LoadFromStorage()
    
  2. 构建 DataDownloader 对象
      # Initialize a report downloader.
      report_downloader = client.GetDataDownloader(version='v201705')
    
  3. 创建查询语句和文件句柄

    在实例化客户端并创建报表下载程序后,请创建您的匹配表所要写入到的文件句柄以及用来过滤的查询语句。

      line_items_file = tempfile.NamedTemporaryFile(
          prefix='line_items_', suffix='.csv', mode='w', delete=False)
      ad_units_file = tempfile.NamedTemporaryFile(
          prefix='ad_units_', suffix='.csv', mode='w', delete=False)
    
      line_items_pql_query = ('SELECT Name, Id, Status FROM Line_Item ORDER BY Id '
                              'ASC')
      ad_units_pql_query = 'SELECT Name, Id FROM Ad_Unit ORDER BY Id ASC'
  4. 将查询和文件句柄传递到 DownloadPqlResultToCsv
    
      # Downloads the response from PQL select statement to the specified file
      report_downloader.DownloadPqlResultToCsv(
          line_items_pql_query, line_items_file)
      report_downloader.DownloadPqlResultToCsv(
          ad_units_pql_query, ad_units_file)
    

发送以下问题的反馈:

此网页
DFP 广告管理系统
DFP 广告管理系统
需要帮助?请访问我们的支持页面