Язык запросов AdWords (AWQL)

AWQL is a SQL–like language for performing queries against most common AdWords API services. Он похож на SQL и подходит для всех сервисов, работающих с методом query().

Хотя язык AWQL создан по образу SQL, он поддерживает не весь словарь SQL. В частности, в нем нет предложений JOIN и GROUP 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>

Аналогичный запрос на языке AWQL для CampaignService.query() будет выглядеть так:

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

В наших клиентских библиотеках есть образцы кода на AWQL, например такой:

Примечания

  • Предложение FROM не требуется, поскольку источник данных уже определен.
  • Предложение DURING недопустимо в вызовах служб, но его можно использовать в вызовах отчетов.
  • В отличие от ключевых слов (например, WHERE) названия полей/столбцов (такие как Name) и литеральных констант (например, ENABLED) чувствительны к регистру.
  • При использовании в предложении WHERE операторов IN и NOT_IN действует ограничение в 10 000 элементов.

Использование AWQL с отчетами

AWQL часто используется в отчетах. Вместо параметра __rdxml метода POST укажите эти два параметра:

  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 запроса не содержит столбец Date или Week).

  • Предложения ORDER BY и LIMIT (упорядочение и разбиение на страницы) НЕ поддерживаются для отчетов. Если включить одно из них в запрос, произойдет ошибка.
  • Чтобы исключить из отчета строки с нулевым количеством показов, добавьте условие 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 нельзя использовать в вызовах служб, но оно необходимо для скачивания отчетов.
  • 2Предложение DURING является необязательным в вызовах служб. Оно требуется при скачивании отчетов, если предложение SELECT запроса содержит столбец Date или Week.
  • 3Для ValueLiteralList прямоугольные скобки [ ] являются обязательными. В остальных случаях они обозначают диапазон.
  • ? означает "необязательно"; * означает "один или больше".
  • Порядок следования: SELECT...FROM...WHERE...DURING...ORDER BY...LIMIT...
  • Все ключевые слова нечувствительны к регистру.
  • Названия столбцов и литеральные константы чувствительны к регистру.
  • Пробелы не имеют значения.
  • Для строк можно использовать как двойные, так и одинарные кавычки. Доступны следующие управляющие последовательности: \", \', \\.

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.