6. 12.

Jak správně používat limit a offset v metodách pro statistické reporty v API Drak

Nejběžnějším využitím API Skliku je bezpochyby stahování statistik. Drak, na rozdíl od předchozí verze Cipísek, má pro toto čtení dvoustavový systém volání – createReport a readReport. Jejich používání vyvolává spousty otázek. Nejčastější z nich je směřována hlavně na nastavení a fungování limitu a offsetu. Tímto článkem se to pokusím co nejvíce objasnit.

Co dělá createReport

Tato metoda si u nás na serveru vytvoří statistický přehled dle zadaných parametrů. Například v ads.createReport můžeme definovat, že chceme inzeráty pouze pro danou kampaň, pouze aktivní inzeráty a další parametry. Po zavolání metody se vytvoří něco jako databázová tabulka, která obsahuje všechna tato data a následně se zamkne (zamezí změnám). Id vytvořené tabulky dostaneme jako návratovou hodnotu [reportId].

Co dělá readReport

Pokud máme hotovo s createReportem a vlastníme id vytvořené tabulky [reportId], můžeme z ní libovolně číst. Důležité je, že tuto tabulku čtením nijak neměníme (nelze ji ani změnit zavoláním dalšího createReport, ten pouze způsobí vytvoření nové tabulky s novým reportId). Všechna omezení, která zadáváme v readReportu fungují jenom tak, že čtecí zařízení vynechává určité sloupce nebo přeskakuje některé řádky. Data v tabulce zůstávají a zachovává se i jejich pořadí.

ReadReport můžeme zavolat například jen se sloupcem „id“ a za hodinu nás napadne, že by bylo dobré znát k hodnotám i příslušnost k sestavě. Přidáme tedy do výpisu sloupec „group.id“. Zavoláním nového readReportu dostaneme zpět stejné množství řádků ve stejném pořadí – jen obohacené o sloupec „group.id“.

Výhody dvoustavového volání

Díky zamknutí tabulky při vytvoření (createReport) se nám v průběhu čtení (readReport) nebudou nechtěně měnit data (přibývat nové imprese, měnit CTR apod.). Navíc můžeme tuto tabulku znovu zavolat i po nějakém čase a opět dostaneme stejná data. Daný přehled se standardně uchovává 2 dny – tato doba není nijak garantovaná a je ovlivněna jinými procesy na serveru.

Popis obou metod je důležitý pro pochopení fungování limitu a offsetu.

Limit a offset

Limit při čtení definuje maximální počet záznamů, které se vyčtou z databáze. Pokud znáte trochu databáze SQL, tak limit i offset má identické vlastnosti. Při nastavení limitu 100 se vyčte nejvýše 100 záznamů bez ohledu na celkové množství (totalCount).

Offset je jakési „posunovátko“. Abychom při každém čtení nezačínali vždy od začátku, můžeme serveru říct, ať začne číst data třeba až od 150. řádku. Při čtení server přeskočí prvních 150 řádků a začne číst od 151 dále (tolik řádků, kolik máme nastavený limit). Důležité je, že pořadí záznamů v databázi je vždy zachované. Prvních 150 záznamů je tedy vždy stejných. Ať zavoláme readReport kolikrát chceme a s jakkoliv pozměněnými parametry.

AllowEmptyStatistics

Velký problém dělá však vlastnost allowEmptyStatistics. Ta se nastavuje v readReportu a v základu je nastavena na hodnotu FALSE. Server v tomto případě při výpisu dat vynechá všechny nulové řádky. Tento filtr ale funguje až nad výčtem dat, které se načetly z tabulky.

Pokud limit nastavíme na 100 záznamů, tak se z tabulky vyčte 100 řádků. Následně se odstraní všechny nulové a my dostaneme 100–0 záznamů. Pokud je například ve 100 záznamech 10 nulových, pak dostaneme pouze 90 záznamů.

Máte k fungování těchto reportů nebo API nějaké dotazy? Neváhejte se na nás obrátit prostřednictvím komentářů.

Za celý tým Skliku

Roman Stejskal