Metoda getAnalyticsData¶
getAnalyticsData¶
Opis ogólny. Metoda pozwala pobrać raport z danymi analitycznymi dla konkretnego projektu. Raporty są budowane w trybie offline. Oznacza to, że należy odpytywać API, aby sprawdzić, czy raport jest gotowy. Metoda: POST Link: https://api.r7k12.com/{{TOKEN}}/getAnalyticsData Nagłówki. Obowiązkowy nagłówek „Content-Type: application/json; charset=UTF-8” Parametry zapytania:
{
"name": (string),
"metrics": [(string),...],
"dimensions": [(string),...],
"date": ("today"|"yesterday"|...|"last 30 day")|[(string),...],
"query": (string),
"bots": (bool),
"eventData":(bool),
"page": (int)
}
Tabela 1 - Opis parametrów
| Parametr | Typ | Opis | Obowiązkowy |
| name | string | Nazwa raportu | Tak |
| metrics | array of string | Metryki raportu (opis w tabeli 2) | Tak |
| dimensions | array of string | Wymiary raportu (opis w tabeli 2). Jeśli zostanie podany nieprawidłowy wymiar raportu, zostanie on pominięty. | Tak |
| date | string or array of string | Typ zakresu dat / przedział dat. today - dzisiaj yesterday - wczoraj week - bieżący tydzień month - bieżący miesiąc previous week - poprzedni tydzień previous month - poprzedni miesiąc last 7 day - ostatnie 7 dni last 10 day - ostatnie 10 dni last 14 day - ostatnie 14 dni last 30 day - ostatnie 30 dni [ ‘Y-m-d’, ‘Y-m-d’ ] - Przedział dat | Tak |
| query | string | Filtr budowania raportu (tabela 3) | Nie |
| bots | bool | Wyklucz boty | Nie |
| eventDate | bool | Uwzględniaj daty zdarzenia | Nie |
| page | int | Żądany numer strony | Nie |
Tabela 2 - Opis filtrów
| Filtry | ||
| == | Dokładne dopasowanie | source1==yandex |
| != | Nie odpowiada | source1!=yandex |
| =@ | Zawiera podciąg | source1=@yandex |
| !@ | Nie zawiera podciągu | source1!@yandex |
| =~ | Zawiera dopasowanie do wyrażenia regularnego | source1=~yandex |
| !~ | Nie pasuje do wyrażenia regularnego | source1!~yandex |
| Łączenie | ||
| , | Logiczne „LUB” | source1==yandex,source1==google |
| ; | Logiczne „ORAZ” | source1==yandex;source1==google |
| *Przy tworzeniu filtrów logiczne „LUB” ma pierwszeństwo przed „ORAZ”. Przykład: filtr postaci source1==yandex;source1==google,source1=facebook będzie odpowiadał (source1 == ‘yandex’ && source1== ’google’) | (source1 == ‘facebook’)* |
Obsługa odpowiedzi:
{
"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)
}
}
Tabela 3 - Pola odpowiedzi
| Nazwa | Typ | Opis | Obecność |
| name | string | Nazwa raportu | Tak (jeśli status - ready) |
| status | string | Status budowania raportu. Główny parametr odpowiedzi, od którego należy zaczynać obsługę. Możliwe warianty: process - raport jest na etapie budowania. W tym przypadku zwracane jest tylko pole „status”. Aby sprawdzić, czy raport jest gotowy, należy powtórzyć zapytanie z tymi samymi parametrami po pewnym czasie. Odstęp czasu określa się na podstawie obecności w odpowiedzi nagłówka „retryIn” - jeśli ten nagłówek jest obecny, ponowne zapytanie należy wysłać po liczbie sekund podanej w tym nagłówku, w przeciwnym razie zapytanie powtarza się po czasie nie krótszym niż 5 sekund - inaczej zostanie zwrócony błąd API. Sprawdzanie nagłówka retryIn jest obowiązkowe. ready - raport jest gotowy. error - błąd budowania raportu | Tak |
| fields | array of object | Opis pól wyświetlanych w raporcie. Pola są podane w tej samej kolejności, w jakiej są wyświetlane w tablicy „data”. | Tak (jeśli status - ready) |
| fields[index].name | string | Nazwa pola (wymiaru/metryki) | Tak (jeśli status - ready) |
| fields[index].type | string | Typ pola: INTEGER | FLOAT |
| fields[index].category | string | Kategoria pola (wymiar/metryka): dimensions | metrics |
| fields[index].description | string | Opis pola | Tak (jeśli status - ready) |
| totals | object | Obiekt zawierający dane sumaryczne dla każdej metryki raportu. | Tak (jeśli status - ready) |
| count | int | łączna liczba wierszy w raporcie | Tak (jeśli status - ready) |
| interval | object | Przedział dat, za który został zbudowany raport | Tak (jeśli status - ready) |
| interval.from | string | Data początkowa w formacie: Y-m-d | Tak (jeśli status - ready) |
| interval.to | string | Data końcowa w formacie: Y-m-d | Tak (jeśli status - ready) |
| pages | int | Liczba stron raportu. Na jednej stronie wyświetla się nie więcej niż 10000 wierszy wyniku. Jeśli stron jest więcej niż 1, należy powtórzyć zapytanie z podaniem parametru „page” | Tak (jeśli status - ready) |
| page | int | Numer żądanej strony raportu | Tak (jeśli status - ready) |
| data | array of array | Tablica z danymi raportu. Każdy wiersz jest zwracany w osobnej tablicy. Kolejność elementów w tablicach wierszy odpowiada kolejności opisu pól w elemencie „fields” | Tak (jeśli status - ready) |
| error | object | Błąd budowania raportu analitycznego. Nie mylić z błędami API | Tak (jeśli status - error) |
| error.code | int | Kod błędu | Tak (jeśli status - error) |
| error.error | string | Błąd | Tak (jeśli status - error) |
| error.error_detail | string | Opis błędu | Tak (jeśli status - error) |
Ograniczenia metody:
- Jednocześnie na serwerze może być przechowywanych nie więcej niż 60 raportów
- Raporty są przechowywane przez jedną godzinę
- Raport wynikowy nie może zawierać więcej niż 1 mln wierszy
- Ilość przetwarzanych danych nie może przekraczać 20 Gb
- Ponowne zapytanie o sprawdzenie statusu raportu należy wysyłać nie wcześniej niż po 5 sek. albo po liczbie sekund podanej w nagłówku „retryIn”.
Tabela 4 - Błędy budowania raportu
| Kod | Błąd | Opis |
| 101 | Nieprawidłowy parametr wejściowy. | Nie podano obowiązkowego pola 'name' (Nazwa raportu). Dozwolone znaki: 0-9,A-Z,a-z,А-Я,а-я,-,_,(,), (spacja). |
| 102 | Nieprawidłowy parametr wejściowy. | Nie podano obowiązkowego pola 'metrics' (Metryki raportu) lub ma ono niedozwolony format. |
| 103 | Nieprawidłowy parametr wejściowy. | Nie podano obowiązkowego pola 'dimensions' (Wymiary raportu) lub ma ono niedozwolony format. |
| 104 | Nieprawidłowy parametr wejściowy. | Pole 'date' (Okres raportu) zawiera nieprawidłową wartość. |
| 105 | Przekroczono limit. | Jednocześnie na serwerze może być przechowywanych nie więcej niż 60 raportów. Raporty są przechowywane 1 godzinę. |
| 106 | Nieprawidłowy parametr wejściowy. | Parametr wejściowy 'page' zawiera nieprawidłową wartość. |
| 111 | Przekroczono limit. | Raport może zawierać nie więcej niż 1 mln rekordów. |
| 112 | Przekroczono limit. | Dozwolone jest nie więcej niż 1 zapytanie w ciągu 5 sekund. |
| 117 | Przekroczono limit. | Przekroczono limit ilości przetwarzanych danych. |
| 0 | Nieznany błąd |
Przykład wywołania metody (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);