Linguagem de consulta do Google AdWords (AWQL, na sigla em inglês)

AWQL is a SQL–like language for performing queries against most common AdWords API services. Todos os serviços com método query() são compatíveis.

O AWQL é inspirado no SQL, embora ele não ofereça suporte a todo o vocabulário SQL. As principais omissões são as cláusulas JOIN e GROUP BY.

Para cada serviço, é possível ver a lista de campos pesquisáveis em Campos do seletor.

Além disso, você pode usar o AWQL para consultar relatórios. Consulte Tipos de relatório para uma lista completa de campos pesquisáveis.

Como usar o AWQL em chamadas de serviço

O AWQL é geralmente uma maneira mais eficiente de codificar a mesma chamada. Por exemplo, este é um seletor que você pode usar para 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>

A string de consulta equivalente do AWQL para CampaignService.query() é:

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

Nossas bibliotecas clientes apresentam exemplos de código que usam AWQL, como este exemplo de código completo para encontrar campanhas com AWQL:

Observações

  • A cláusula FROM não é necessária, já que a fonte de dados é determinada pelo serviço ao qual a solicitação é enviada.
  • A cláusula DURING é permitida em chamadas de relatório, mas não em chamadas de serviço.
  • O campo (coluna), os nomes (como Name) e os literais (como ENABLED) diferenciam maiúsculas e minúsculas, embora as palavras-chave (por exemplo, WHERE) não as diferencie.
  • Ao usar os operadores IN e NOT_IN na cláusula WHERE, há um limite de 10.000 itens.

Como usar o AWQL com relatórios

O AWQL é frequentemente usado em relatórios. Em vez de especificar o fragmento XML no parâmetro POST "__rdxml", como você faria normalmente para relatórios, forneça estes dois parâmetros:

  1. "__rdquery": contém a string de consulta do AWQL.
  2. "__fmt": define o formato de download do relatório.

Exemplo (corpo POST):

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

Há também algumas diferenças de uso quando se recorre ao AWQL para a geração de relatórios:

  • A consulta precisa conter um tipo de relatório na cláusula FROM, por exemplo:

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

    Embora a cláusula FROM não seja permitida em chamadas de serviço, ela é obrigatória para fazer o download de relatórios.

  • Os períodos do relatório são definidos na cláusula DURING da consulta. Eles podem ser especificados de duas maneiras diferentes:

    1. Um período personalizado que utiliza a sintaxe comum do AWQL, por exemplo:

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

    2. Um tipo de período, por exemplo:

      SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING LAST_7_DAYS

  • Para ver dados de todas as datas (equivalente a ALL_TIME), você pode omitir da sua consulta a cláusula DURING. No entanto, isso só é permitido se a cláusula SELECT da sua consulta não incluir a coluna Date ou Week.

  • ORDER BY e LIMIT (classificação e paginação) NÃO são compatíveis com relatórios. Incluir essas cláusulas em uma consulta resultará em um erro.
  • Para omitir linhas com impressão inexistente, inclua uma condição WHERE Impressions > 0.

Gramática formal

Veja abaixo a gramática formal do AWQL para referência.

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

Observações

  • 1FROM não é permitida em chamadas de serviço, mas é obrigatória para fazer o download de relatórios.
  • 2 DURING é opcional em chamadas de serviço. Ela é obrigatória para fazer o download de relatórios quando a cláusula SELECT da sua solicitação inclui a coluna Date ou Week.
  • 3Para ValueLiteralList, é necessário usar colchetes [ ]. Em outros lugares, eles representam um intervalo.
  • ? significa opcional e * significa um ou mais.
  • Ordem: SELECT...FROM...WHERE...DURING...ORDER BY...LIMIT...
  • Todas as palavras-chave reconhecem letras maiúsculas e minúsculas.
  • Os nomes de colunas e os literais reconhecem letras maiúsculas e minúsculas.
  • O espaço em branco não tem importância.
  • As aspas simples e as aspas duplas são aceitas para strings. As sequências de escape são \", \' e \\.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.