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 PQL e como usá-la para filtrar vários tipos de objetos.

A sintaxe PQL pode ser resumida da seguinte forma:

[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 têm escape 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 (não diferencia maiúsculas de minúsculas)

  • WHERE: expressa um conjunto de zero ou mais condições, mescladas opcionalmente usando as frases AND ou OR. É possível agrupar as frases AND ou OR com parênteses. Executando a consulta "" (vazio string) retorna tudo.

    Exemplos: WHERE width = 728

    de 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ê deseja verificar um dos diversos valores de um único 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. A LIMIT também pode incluir um <offset>, que é quantas linhas do início serão deslocadas do conjunto de resultados.

    Exemplos (os dois exemplos 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 51-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 suportadas por uma . Portanto, verifique a lista abaixo para ver quais propriedades suportam 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. Curingas não têm suporte.
  • IN: compara o valor de uma propriedade a cada item em uma list; se algum deles corresponder, será uma correspondência positiva. O IN é equivalente a várias consultas =, uma para cada valor. que são combinados como 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 a cada item em uma lista. se nenhum for correspondente, é uma correspondência positiva. O NOT IN é equivalente a várias consultas !=, uma para cada valor. que são combinados como 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 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 um formatada de acordo com o 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ências oferecem um mecanismo de pesquisa para os valores brutos contidos em arquivos de transferência de dados, permitindo que você combine informações de veiculação de anúncios (como unidade ou item de linha) a valores pré-atribuídos armazenados no banco de dados.

Se você gerar relatórios por meio das APIs ReportService ou com a Transferência de dados da Web, convém complementar os dados do relatório com mais 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 tenha o campo LineItemId, é possível criar uma tabela de correspondências que inclua a data de início de cada item de linha, data de término, tipo, status e outros atributos úteis.

Há várias maneiras de realizar essa funcionalidade de correspondência:

  1. Use as tabelas de correspondências 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 BigQuery ou PQL para a entidade ou se a tabela não tiver os campos necessários, você poderá usar isso. serviço da entidade diretamente, como o OrderService.
Python

Configurar uma consulta de relatório

Comece criando um trabalho de relatório, especificando os parâmetros do relatório, 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='v202408')

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)

Fazer o download de dados da tabela de PQL de itens de linha

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 interface pandas porque isso torna o trabalho com dados tabulares muito mais fácil. 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