Esta página foi traduzida pela API Cloud Translation.

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

Sintaxe e uso da PQL

PQL é uma linguagem semelhante a SQL para consultar objetos. A sintaxe da 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

Palavras-chave 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 strings 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 diferenciam maiúsculas de minúsculas)

WHERE: expressa um conjunto de zero ou mais condições, opcionalmente combinadas usando as frases AND ou OR. É possível agrupar as frases AND ou OR com parênteses. Executar a consulta "" (string vazia) 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, mas apenas uma delas precisa ser verdadeira. Se você quiser verificar um dos diversos valores de uma única propriedade, use a cláusula IN.
Exemplo: WHERE width = 728 OR height = 90.
AND: mescla 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 ordem crescente (ASC em que "A" é o primeiro) ou decrescente (DESC em que "A" é o último). Se a direção não for especificada, o padrão será ASC. Se essa cláusula não for incluída, o padrão será 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 representa quantas linhas do início são necessárias para desviar o 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 no conjunto de resultados para começar a retornar valores. Use 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 a PQL. Normalmente, não é possível filtrar todas as propriedades compatíveis com um objeto. Por isso, verifique a lista abaixo para ver quais propriedades aceitam consultas PQL. Por exemplo, as propriedades do criativo que podem ser filtradas incluem id, name, width e height.
<value>: os valores de string precisam ser colocados entre aspas simples ('). Os valores numéricos podem ser citados ou sem aspas. Caracteres curinga não são aceitos.
IN: compara o valor de uma propriedade com cada item de uma lista. Se algum deles corresponder, será uma correspondência positiva. O operador IN equivale a muitas consultas =, uma para cada valor, que são combinadas como OR. Os valores são especificados como uma lista separada por vírgulas, entre parênteses: (a, b, c). Todos os valores da lista são avaliados.
Exemplo: WHERE name IN ('CompanyNameA', 'CompanyNameB').
NOT IN: compara o valor de uma propriedade com cada item de uma lista. Se nenhum item corresponder, é uma correspondência positiva. O operador NOT IN equivale a muitas consultas !=, uma para cada valor, que são combinadas como OR. Os valores são especificados como uma lista separada por vírgulas, entre parênteses: (a, b, c). Todos os valores da lista são avaliados.
Exemplo: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB').
LIKE: permite consultar objetos usando a correspondência de string de caracteres curinga. O sinal de porcentagem (%) representa zero, um ou vários caracteres. Use um par para incluir a string de pesquisa que está sendo correspondida.
Exemplos: WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'
IS NULL: permite que você consulte objetos com um valor de propriedade indefinido. O exemplo clássico disso é consultar a AdUnit raiz consultando um AdUnit com um ID pai nulo.
Exemplo: WHERE parentId IS NULL.

<bind variable>: é possível usar objetos Value no lugar de valores <value> codificados na consulta PQL. Uma variável de vinculação é mencionada na PQL usando um nome de string sem espaços, começando com : (dois-pontos).

Exemplo (cria uma consulta e insere duas variáveis no lugar dos valores de propriedade id e status codificados):

// 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 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);

Buscando tabelas de correspondências com PQL

As tabelas de correspondências fornecem um mecanismo de pesquisa dos 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 por meio do ReportService ou com relatórios da Transferência de dados, convém complementar os dados do relatório com campos adicionais. Por exemplo, com um relatório que tenha 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, data de término, tipo, status e outros atributos úteis de cada item de linha.

Existem várias maneiras de usar essa funcionalidade de correspondência:

Use as tabelas de correspondências predefinidas fornecidas pelo serviço de transferência de dados do BigQuery. Essas tabelas de correspondência não contêm todos os campos de entidade.
Uma abordagem eficiente é usar qualquer uma das tabelas PublisherQueryLanguageService disponíveis.
Se não houver uma tabela do BigQuery ou PQL para a entidade ou se a tabela não tiver os campos necessários, será possível usar o serviço da entidade diretamente, como OrderService.

Python

Configurar uma consulta de relatório

Comece criando um job 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
    }
}

Fazer o download do relatório

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

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 dos dados da tabela PQL Line_Item

Para corresponder seu relatório a outros dados de itens de linha, use a tabela PQL Line_Item.

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

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

Este exemplo usa a biblioteca pandas, porque torna muito mais fácil trabalhar com dados tabulares. Aqui, ele é usado para mesclar os dados do relatório e 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