Guia para desenvolvedores da Linguagem de consulta do editor (PQL)

Sintaxe e uso da PQL

PQL é uma linguagem semelhante a SQL para consulta de objetos. A sintaxe PQL é semelhante à do SQL, com algumas diferenças descritas aqui. Esta seção descreve a sintaxe do PQL e como usá-la para filtrar vários tipos de objetos.

A sintaxe PQL pode ser resumida da seguinte maneira:

[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>

Observações

  • As palavras-chave da PQL não diferenciam maiúsculas de minúsculas.
  • As strings são codificadas automaticamente quando usadas em parâmetros de vinculação. Caso contrário:

    • Para uma string entre aspas simples (apóstrofos), faça o escape de qualquer apóstrofo adicional escrevendo-o como um par de aspas simples.

      Exemplo: "WHERE name = 'Company''s name'".

Palavras-chave (sem distinção entre maiúsculas e minúsculas)

  • WHERE: expressa um conjunto de zero ou mais condições, opcionalmente agrupadas usando frases AND ou OR. Você pode agrupar frases AND ou OR com parênteses. Executando a consulta "" (vazia) string) retorna tudo.

    Exemplos: WHERE width = 728
    WHERE width = 728 AND height = 90
    WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

  • OR: combina várias condições, somente uma delas precisa ser verdade. Se você quiser verificar vários valores para uma única propriedade, use uma cláusula IN.

    Exemplo: WHERE width = 728 OR height = 90.

  • AND: combina várias condições que precisam ser satisfeitas usando a cláusula AND.

    Exemplo: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB').

  • ORDER BY: classifica os resultados retornados em crescente (ASC onde "A" é o primeiro) ou decrescente (DESC, em que "A" é o último). Se a direção não for especificado, o padrão é ASC. Se esta cláusula não for incluída o padrão é ASC no primeiro campo.

    Exemplo: WHERE id IN (5008, 8745, 3487) ORDER BY id.

  • LIMIT: o número de resultados a serem retornados. O LIMIT também pode incluir um <offset>, que é quantas linhas do início serão deslocadas do conjunto de resultados.

    Exemplos (ambos retornam o mesmo conjunto de resultados):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET: o deslocamento do conjunto de resultados para iniciar valores de retorno. Use isso para paginar os resultados.

    Exemplo (retorna resultados de 51 a 100):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property>: uma das propriedades expostas pelo objeto. Cada objeto expõe propriedades diferentes que podem ser filtradas usando PQL. Normalmente, não é possível filtrar todas as propriedades aceitas por um objeto. Confira a lista abaixo para ver quais propriedades são compatíveis com consultas PQL. Por exemplo, as propriedades do criativo que podem ser filtradas incluem id, name, width e height.
  • <value>: os valores de string precisam estar entre aspas aspas simples ('). Os valores numéricos podem ser citados ou não. Caracteres curinga não são aceitos.
  • IN: compara o valor de uma propriedade a cada item em uma list; se algum for correspondente, será uma correspondência positiva. O operador IN equivale a muitas consultas =, uma para cada valor, que são combinadas com o OR. Os valores são especificados como uma lista separada por vírgulas de valores entre parênteses: (a, b, c). Todos os valores da lista são avaliado.

    Exemplo: WHERE name IN ('CompanyNameA', 'CompanyNameB').

  • NOT IN: compara o valor de uma propriedade com cada item em uma lista. Se nenhum corresponder, será uma correspondência positiva. O operador NOT IN equivale a muitas consultas !=, uma para cada valor, que são combinadas com o OR. Os valores são especificados como uma lista separada por vírgulas de valores, entre parênteses: (a, b, c). Todos os valores na lista são avaliados.

    Exemplo: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB').

  • LIKE: permite consultar objetos usando caracteres curinga. correspondência de string. O sinal de porcentagem (%) representa zero, um ou vários caracteres. Use um par para incluir a string de pesquisa correspondente.

    Exemplos: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL: permite que você consulte objetos com uma valor de propriedade indefinido. Um exemplo clássico é consultar o raiz de AdUnit consultando um AdUnit com um valor nulo ID de pai.

    Exemplo: WHERE parentId IS NULL.

  • <bind variable>: você pode usar Value objetos no lugar do <value> codificado na consulta PQL. Uma vinculação é referenciada na PQL usando um nome de string sem espaços, começando por : (dois pontos).

    Exemplo (cria uma consulta e insere duas variáveis no lugar de as propriedades id e status fixadas no código valores de referência):

    // 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);
  • Campos DateTime: é possível filtrar por data e hora atribuindo um valor DateTime a uma variável de vinculação ou usando uma string formatada de acordo com a ISO 8601. 
    // Create a bind variable: startDateTime
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 < '2019-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500");
statement.setValues(values);

Buscar tabelas de correspondências com PQL

As tabelas de correspondência fornecem um mecanismo de pesquisa para os valores brutos contidos nos arquivos de transferência de dados, permitindo que você combine informações de veiculação de anúncios (como bloco de anúncios ou item de linha) com valores pré-atribuídos armazenados no banco de dados.

Se você estiver gerando relatórios pelo ReportService ou com relatórios de transferência de dados, é recomendável complementar os dados do relatório com outros campos. Por exemplo, com um relatório que tem a dimensão LINE_ITEM_ID ou com um evento de transferência de dados que tem o campo LineItemId, é possível criar uma tabela de correspondência que inclui a data de início, a data de término, o tipo, o status e outros atributos úteis de cada item de linha.

Há várias maneiras de fazer isso:

  1. Use as tabelas de correspondência pré-criadas fornecidas pelo serviço de transferência de dados do BigQuery. Observe que essas tabelas de correspondências não contêm todos os campos de entidade.
  2. Uma abordagem eficiente é usar qualquer um dos PublisherQueryLanguageService tabelas.
  3. Se não houver uma tabela do BigQuery ou PQL para a entidade ou se a tabela não tiver os campos necessários, acesse o serviço da entidade diretamente, como o OrderService.

Python

Configurar uma consulta de relatório

Comece criando um job de relatório, especificando os parâmetros, como dimensões, colunas e período.

# 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
    }
}

Baixe o relatório (em inglês)

# Initialize a DataDownloader.
report_downloader = client.GetDataDownloader(version='v202508')

try:
  # Run the report and wait for it to finish.
  report_job_id = report_downloader.WaitForReport(report_job)
except errors.AdManagerReportError as 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)

Faça o download de dados da tabela de PQL de linha_item

Para corresponder seu relatório com dados adicionais do item de linha, use o atributo Line_Item tabela 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)

Mesclar os dados do relatório com os do item de linha

Este exemplo usa a biblioteca pandas, que facilita muito o trabalho com dados tabulares. Aqui, é usado para mesclar os dados do relatório com os da PQL para criar uma tabela de correspondências.

# 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)
 Ver no GitHub