Ищете REST API? API Менеджера рекламы (бета-версия) теперь доступен.

Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Руководство для разработчиков по языку Publisher Query Language (PQL)

Синтаксис и использование PQL

PQL – это язык запросов, похожий на SQL. Синтаксис PQL похож на синтаксис SQL, но имеет некоторые отличия, описанные ниже. В этом разделе описывается синтаксис PQL и его использование для фильтрации объектов различных типов.

Синтаксис PQL можно кратко описать следующим образом:

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

Примечания

Ключевые слова PQL не чувствительны к регистру.
Строки автоматически экранируются при использовании в параметрах привязки. В противном случае:
- Если строка заключена в одинарные кавычки (апострофы), то все дополнительные апострофы нужно экранировать, записывая их как пару одинарных кавычек.
  Пример: "WHERE name = 'Company''s name'".

Ключевые слова (без учета регистра)

WHERE – набор из нуля или более условий, которые могут быть объединены с помощью операторов AND или OR. Фразы с операторами AND или OR можно заключать в скобки. Если выполнить запрос "" (пустая строка), будут возвращены все данные.
Примеры: WHERE width = 728
WHERE width = 728 AND height = 90
WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)
OR – объединяет несколько условий, из которых только одно должно быть истинным. Если вы хотите проверить несколько значений для одного свойства, используйте предложение IN.
Пример: WHERE width = 728 OR height = 90.
AND – объединяет несколько условий, которые должны выполняться одновременно, с помощью оператора AND.
Пример: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB').
ORDER BY – сортирует результаты по возрастанию (ASC, где "A" – первый элемент) или по убыванию (DESC, где "A" – последний элемент). Если направление не указано, по умолчанию используется ASC. Если это условие не включено, по умолчанию используется ASC для первого поля.
Пример: WHERE id IN (5008, 8745, 3487) ORDER BY id.
LIMIT – количество результатов, которые нужно вернуть. В LIMIT также можно включить <offset>, чтобы указать, сколько строк от начала нужно пропустить в наборе результатов.
Примеры (оба примера возвращают один и тот же набор результатов):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
WHERE type = 'AGENCY' LIMIT 50,50
OFFSET – смещение в наборе результатов, с которого начинается возврат значений. Используйте их для перехода между страницами.
Пример (возвращает результаты 51–100):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.
<property> – одно из свойств, предоставляемых объектом. Каждый объект имеет разные свойства, по которым можно выполнять фильтрацию с помощью PQL. Обычно фильтрация по всем свойствам, поддерживаемым объектом, невозможна, поэтому ознакомьтесь со списком ниже, чтобы узнать, какие свойства поддерживают запросы PQL. Например, можно фильтровать креативы по следующим свойствам: id, name, width и height.
<value> – строковые значения должны быть заключены в одинарные кавычки ('). Числовые значения можно указывать в кавычках или без них. Подстановочные знаки не поддерживаются.
IN – сравнивает значение свойства с каждым элементом в списке. Если совпадение найдено, возвращает положительный результат. Оператор IN эквивалентен нескольким запросам = (по одному для каждого значения), объединенным оператором OR. Значения указываются в виде списка, разделенного запятыми и заключенного в круглые скобки: (a, b, c). Оцениваются все значения в списке.
Пример: WHERE name IN ('CompanyNameA', 'CompanyNameB').
NOT IN – сравнивает значение свойства с каждым элементом в списке. Если совпадений нет, возвращает положительный результат. Оператор NOT IN эквивалентен нескольким запросам != (по одному для каждого значения), объединенным оператором OR. Значения указываются в виде списка, разделенного запятыми и заключенного в круглые скобки: (a, b, c). Оцениваются все значения в списке.
Пример: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB').
LIKE – позволяет запрашивать объекты с помощью подстановочных знаков. Знак процента (%) представляет ноль, один или несколько символов. Используйте пару, чтобы заключить в нее поисковый запрос.
Примеры: WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'
IS NULL – позволяет запрашивать объекты с неопределенным значением свойства. Классический пример – запрос корневого объекта AdUnit путем запроса объекта AdUnit с нулевым идентификатором родительского объекта.
Пример: WHERE parentId IS NULL.
<bind variable> – вместо заданных в коде значений <value> в PQL-запросе можно использовать объекты Value. В PQL связанная переменная обозначается строковым именем без пробелов, которое начинается с двоеточия (:).
Пример (создает запрос и вводит две переменные вместо заданных в коде значений свойств id и status):
```
// 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);
```

Поля DateTime. Вы можете фильтровать данные по дате и времени, присваивая значение DateTime связанной переменной или используя строку, отформатированную в соответствии со стандартом 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);

Как получать таблицы соответствий с помощью PQL

Таблицы соответствия позволяют выполнять поиск идентификаторов по названиям и сопоставлять информацию о показе объявления из файлов передачи данных (например, о рекламном блоке или позиции) с предварительно заданными значениями из базы данных.

Если вы создаете отчеты с помощью ReportService или передачи данных, то можете дополнить их новыми полями. Например, если в отчете есть параметр LINE_ITEM_ID или в событии передачи данных есть поле LineItemId, вы можете создать таблицу сопоставления, в которой будут указаны даты начала и окончания показа, тип, статус и другие атрибуты каждой позиции.

Это можно сделать несколькими способами:

Используйте готовые таблицы сопоставления, предоставляемые сервисом BigQuery Data Transfer. Обратите внимание, что в этих таблицах сопоставления представлены не все поля объектов.
Эффективный подход заключается в использовании любой из доступных таблиц PublisherQueryLanguageService.
Если для объекта нет таблицы BigQuery или PQL или в таблице отсутствуют нужные поля, вы можете обратиться к сервису этого объекта напрямую, например к OrderService.

Python

Как настроить запрос отчета

Сначала создайте задание отчета, указав его параметры, такие как параметры, столбцы и диапазон дат.

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

Скачать отчет

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

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)

Как скачать данные из таблицы Line_Item PQL

Чтобы сопоставить отчет с дополнительными данными о позициях, используйте таблицу 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)

Как объединить данные отчета с данными позиции

В этом примере используется библиотека pandas, поскольку она значительно упрощает работу с табличными данными. В данном случае он используется для объединения данных отчета с данными PQL, чтобы создать таблицу соответствия.

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

Посмотреть на GitHub