Метод getAnalyticsData¶
getAnalyticsData¶
Общее описание. Метод позволяет получить отчет с данными аналитики по конкретному проекту. Отчеты строятся в офлайн-режиме. То есть необходимо проводить опрос API на предмет готовности отчета. Метод: POST Ссылка: https://api.r7k12.ru/{{TOKEN}}/getAnalyticsData Заголовки. Обязательный заголовок “Content-Type: application/json; charset=UTF-8” Параметры запроса:
{
"name": (string),
"metrics": [(string),...],
"dimensions": [(string),...],
"date": ("today"|"yesterday"|...|"last 30 day")|[(string),...],
"query": (string),
"bots": (bool),
"eventData":(bool),
"page": (int)
}
Таблица 1 - Описание параметров
| Параметр | Тип | Описание | Обязательный |
| name | string | Название отчета | Да |
| metrics | array of string | Показатели отчета (описание в таблице 2) | Да |
| dimensions | array of string | Параметры отчета (описание в таблице 2). При указании некорректного параметра отчета - он будет пропущен. | Да |
| date | string or array of string | Тип диапазона дат / интервал дат. today - сегодня yesterday - вчера week - текущая неделя month - текущий месяц previous week - предыдущая неделя previous month - предыдущий месяц last 7 day - последние 7 дней last 10 day - последние 10 дней last 14 day - последние 14 дней last 30 day - последние 30 дней [ ‘Y-m-d’, ‘Y-m-d’ ] - Интервал дат | Да |
| query | string | Фильтр построения отчета (таблица 3) | Нет |
| bots | bool | Не учитывать ботов | Нет |
| eventDate | bool | Учитывать даты события | Нет |
| page | int | Запрашиваемый номер страницы | Нет |
Таблица 2 - Описание фильтров
| Фильтры | ||
| == | Точное соответствие | source1==yandex |
| != | Не соответствует | source1!=yandex |
| =@ | Содержит подстроку | source1=@yandex |
| !@ | Не содержит подстроку | source1!@yandex |
| =~ | Содержит совпадение для регулярного выражения | source1=~yandex |
| !~ | Не соответствует регулярному выражению | source1!~yandex |
| Объединение | ||
| , | Логическое “ИЛИ” | source1==yandex,source1==google |
| ; | Логическое “И” | source1==yandex;source1==google |
| *При формировании фильтров логическое “ИЛИ” в приоритете над “И”. Пример: фильтр вида source1==yandex;source1==google,source1=facebook будет соответствовать (source1 == ‘yandex’ && source1== ’google’) | (source1 == ‘facebook’)* |
Обработка ответа:
{
"name": (string),
"status": (string),
"fields": (array of object) [
{
"name": (string),
"type": (string),
"category": (string),
"description": (string)
},
…….
],
"totals": (object),
"count": (int),
"interval": (object) {
"from": (string),
"to": (string)
},
"pages": (int),
"page": (int),
"data": (array of array),
"error": (object){
"code": (int),
"error": (string),
"error_detail": (string)
}
}
Таблица 3 - Поля ответа
| Название | Тип | Описание | Наличие |
| name | string | Название отчета | Да (если status - ready) |
| status | string | Статус построения отчета. Главный параметр ответа, с которого необходимо начинать обработку. Возможные варианты: process - отчет находится на этапе построения. В данном случае возвращается только поле “status”. Для проверки готовности отчета необходимо повторить запрос с теми же параметрами через некоторый интервал времени. Интервал времени определяется исходя из наличия в ответе заголовка “retryIn” - если данный заголовок присутствует то повторный запрос необходимо повторить через кол-во секунд указанное в данном заголовке иначе запрос повторяется через интервал времени не менее 5 секунд - иначе будет получена ошибка API. Проверка заголовка retryIn является обязательной. ready - отчет готов. error - ошибка построения отчета | Да |
| fields | array of object | Описание полей выводимых в отчет. Поля указаны в том порядке в котором они выводятся в массиве “data”. | Да (если status - ready) |
| fields[index].name | string | Название поля (параметра/показателя) | Да (если status - ready) |
| fields[index].type | string | Тип поля: INTEGER | FLOAT |
| fields[index].category | string | Категория поля (параметр/показатель): dimensions | metrics |
| fields[index].description | string | Описание поля | Да (если status - ready) |
| totals | object | Объект содержащий итоговые данные по каждому показателю отчета. | Да (если status - ready) |
| count | int | общее кол-во строк в отчете | Да (если status - ready) |
| interval | object | Интервал дат за который был построен отчет | Да (если status - ready) |
| interval.from | string | Начальная дата в формате: Y-m-d | Да (если status - ready) |
| interval.to | string | Конечная дата в формате: Y-m-d | Да (если status - ready) |
| pages | int | Кол-во страниц отчета. На одной странице выводится не более 10000 строк результат. В случае если страниц более 1 то необходимо повторить запрос с указанием параметра “page” | Да (если status - ready) |
| page | int | Номер запрашиваемой страницы отчета | Да (если status - ready) |
| data | array of array | Массив с данными отчета. Каждая строка выводится в отдельном массиве. Последовательность элементов в массивах строк соответствует последовательности описания полей в элементе “fields” | Да (если status - ready) |
| error | object | Ошибка построения отчета аналитики. Не путать с ошибками API | Да (если status - error) |
| error.code | int | Код ошибки | Да (если status - error) |
| error.error | string | Ошибка | Да (если status - error) |
| error.error_detail | string | Описание ошибки | Да (если status - error) |
Ограничения метода:
- Одновременно на сервере может хранится не более 60 отчетов
- Отчеты хранятся в течении одного часа
- Результирующий отчет не может содержать более 1 млн. строк
- Кол-во обрабатываемых данных не может превышать 20 Gb
- Повторный запрос на проверку статуса отчета отправлять не ранее чем через 5 сек. либо через кол-во секунд указанное в заголовке “retryIn”.
Таблица 4 - Ошибки построения отчета
| Код | Ошибка | Описание |
| 101 | Некорректный входной параметр. | Не задано обязательное поле 'name' (Название отчета). Допустимые символы: 0-9,A-Z,a-z,А-Я,а-я,-,_,(,), (пробел). |
| 102 | Некорректный входной параметр. | Не задано обязательное поле 'metrics' (Показатели отчета), либо имеет недопустимый формат. |
| 103 | Некорректный входной параметр. | Не задано обязательное поле 'dimensions' (Параметры отчета), либо имеет недопустимый формат. |
| 104 | Некорректный входной параметр. | Поле 'date' (Период отчета) содержит некорректное значение. |
| 105 | Превышена квота. | Одновременно на сервере может хранится не более 60 отчетов. Отчеты хранятся 1 час. |
| 106 | Некорректный входной параметр. | Входной параметр 'page' содержит некорректное значение. |
| 111 | Превышена квота. | Отчет может содержать не более 1 млн записей. |
| 112 | Превышена квота. | Разрешено не более 1 запрос в течении 5 секунд. |
| 117 | Превышена квота. | Превышена квота объема обрабатываемых данных. |
| 0 | Неизвестная ошибка |
Пример вызова метода (PHP):
define('TOKEN','YOURTOKEN');
function POST ($request) {
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.r7k12.ru/'.TOKEN.'/getAnalyticsData');
curl_setopt($curl, CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($request,JSON_UNESCAPED_UNICODE));
$out = curl_exec($curl);
curl_close($curl);
return json_decode($out,true);
}
$response = POST(
[
'name' => 'API R7K12',
'metrics' => [
'sessions',
'cost',
'impressions'
],
'dimensions' => [
'nameProject',
'idProject'
],
'date' => 'today',
'bots' => true,
'eventDate' => false
]
);
print_r($response);