AdWords 查询语言 (AWQL)

AWQL 是一种与 SQL 类似的语言,用于对最常见的 AdWords API 服务执行查询。这种语言支持所有提供 query() 方法的服务。

AWQL 的开发灵感源自 SQL,但它并没有全面支持所有 SQL 语汇。值得注意的是,这种语言省略了 JOINGROUP BY 子句。

对于每项服务,您可以从选择器字段中获取可查询字段的列表。

此外,还可以使用 AWQL 查询报告。有关可查询字段的完整列表,请参阅报告类型

在服务调用中使用 AWQL

对于相同的调用,使用 AWQL 来编写调用代码通常更为高效。例如,对于 CampaignService.get(),您可以使用下面的选择器:

<serviceSelector>
    <fields>Id</fields>
    <fields>Name</fields>
    <predicates>
        <field>Status</field>
        <operator>EQUALS</operator>
        <values>ENABLED</values>
    </predicates>
    <ordering>
        <field>Name</field>
        <sortOrder>ASCENDING</sortOrder>
    </ordering>
    <paging>
        <startIndex>0</startIndex>
        <numberResults>50</numberResults>
    </paging>
</serviceSelector>

同样是 CampaignService.query(),等效的 AWQL 查询字符串则是:

SELECT Id, Name
WHERE Status = 'ENABLED'
ORDER BY Name
DESC LIMIT 0,50

我们的客户端库主要提供的是使用 AWQL 的代码示例,下面就是一个使用 AWQL 获取广告系列的完整代码示例:

备注

  • 因为请求所发送到的服务已确定数据源,所以不需要 FROM 子句。
  • 服务调用中不允许使用 DURING 子句,但报告调用中可以使用这一子句。
  • 虽然关键字(如 WHERE)不区分大小写,但字段(列)名(如 Name)和字面值(如 ENABLED区分大小写
  • WHERE 子句中使用 INNOT_IN 运算符时,最多可以指定 10000 个条目。

将 AWQL 用于报告

AWQL 经常用在报告中。与通常在报告的“__rdxmlPOST 参数中指定 XML 片段不同,需要提供以下两个参数:

  1. __rdquery”:包含 AWQL 查询字符串。
  2. __fmt”:定义报告的下载格式

示例(POST 正文):

__rdquery=SELECT+Criteria+FROM+KEYWORDS_PERFORMANCE_REPORT+DURING+20150101,20150325&__fmt=CSV

下面还列出了将 AWQL 用于报告时的一些用法差异:

  • 查询必须在 FROM 子句中包含报告类型,例如:

    SELECT Id, Criteria, AdGroupName **FROM KEYWORDS_PERFORMANCE_REPORT**

    请注意,尽管在服务调用中不允许使用 FROM,但在报告下载中必须使用该子句。

  • 报告的日期范围在查询的 DURING 子句中定义。可以通过以下两种不同的方式指定日期范围:

    1. 使用常规 AWQL 句法规则的自定义日期范围,例如:

      SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING 20160101,20160325

    2. 日期范围类型,例如:

      SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING LAST_7_DAYS

  • 要获取所有日期的数据(等效于 ALL_TIME),可以在查询中省略 DURING 子句。但是,只有当您的查询的 SELECT 子句没有包含 DateWeek 列时,才允许如此操作。

  • 就报告而言,支持 ORDER BYLIMIT(排序和分页)。在查询中加入这些子句将发生错误。
  • 要忽略展示次数为零的行,请加入 WHERE Impressions > 0 条件。

形式语法

下面列出了 AWQL 形式语法以供参考。

Statement        -> SelectClause FromClause1 WhereClause?
                                 DuringClause2 OrderByClause? LimitClause?
SelectClause     -> SELECT ColumnList
FromClause       -> FROM SourceName
WhereClause      -> WHERE ConditionList
DuringClause     -> DURING DateRange
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT StartIndex , PageSize

ConditionList    -> Condition (AND Condition)*
Condition        -> ColumnName Operator Value
Value            -> ValueLiteral | String | ValueLiteralList | StringList
Ordering         -> ColumnName (DESC | ASC)?
DateRange        -> DateRangeLiteral | Date,Date
ColumnList       -> ColumnName (, ColumnName)*
ColumnName       -> Literal
SourceName       -> Literal
StartIndex       -> Non-negative integer
PageSize         -> Non-negative integer

Operator         -> = | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
                    CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE |
                    CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL
String           -> StringSingleQ | StringDoubleQ
StringSingleQ    -> '(char)'
StringDoubleQ    -> "(char)"
StringList       -> [ String (, String)* ]
ValueLiteral     -> [a-zA-Z0-9_.]*
ValueLiteralList -> **[** ValueLiteral (, ValueLiteral)* **]**3
Literal          -> [a-zA-Z0-9_]*
DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | THIS_WEEK_SUN_TODAY | THIS_WEEK_MON_TODAY | LAST_WEEK |
                    LAST_14_DAYS | LAST_30_DAYS | LAST_BUSINESS_WEEK | LAST_WEEK_SUN_SAT | THIS_MONTH
Date             -> 8-digit integer: YYYYMMDD

备注

  • 1在服务调用中不允许使用 FROM 子句,但在报告下载中必须使用该子句。
  • 2DURING 在服务调用中是可选的。如果您的请求的 SELECT 子句包含 DateWeek 列,则在报告下载中必须使用该子句。
  • 3对于 ValueLiteralList,必须使用方括号 ([ ]);而方括号在其他地方用来表示范围。
  • ? 表示可选;* 表示一个或多个。
  • 顺序:SELECT...FROM...WHERE...DURING...ORDER BY...LIMIT...
  • 所有关键字均不区分大小写。
  • 列名称和字面值是区分大小写的。
  • 空格不起作用。
  • 可以在字符串中使用双引号和单引号。相应的转义序列为 \"\'\\

发送以下问题的反馈:

此网页
AdWords API
AdWords API
需要帮助?请访问我们的支持页面