Към съдържанието

Методът getAnalyticsData

getAnalyticsData

Общо описание. Методът позволява да получите отчет с данни от аналитиката за конкретен проект. Отчетите се изграждат в офлайн режим. Тоест е необходимо да се изпращат заявки към API, за да се провери дали отчетът е готов. Метод: POST Линк: https://api.r7k12.com/{{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)

Ограничения на метода:

  1. Едновременно на сървъра могат да се съхраняват не повече от 60 отчета
  2. Отчетите се съхраняват в продължение на един час
  3. Крайният отчет не може да съдържа повече от 1 млн. реда
  4. Обемът на обработваните данни не може да надвишава 20 Gb
  5. Повторната заявка за проверка на статуса на отчета да се изпраща не по-рано от 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.com/'.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);