Filtrování výpisu kontaktů získaných přes API

Jaroslav Bouška Jaroslav Bouška
7. září 2023

Odesláním požadavku na koncový bod API GET /v1/contacts získáme seznam všech kontaktů včetně jejich vlastností, jako jsou křestní jméno, příjmení anebo například e-mail. Pomocí filtru můžeme výsledný seznam blíže specifikovat a pracovat s jednotlivými kontakty efektivněji.

Pomocí filtrování si můžete vypsat například kontakty, které se do vaší databáze zaregistrovaly později než 31. ledna 2020, nebo u nichž je uvedena velikost boty větší než 45. Níže najdete postup, jak na to.

Dřívější verze rozhraní API neumožňovala filtrování kontaktů podle dat v uživatelských sloupcích. Nový filtr kontaktů již tohle umožňuje a navíc můžete použít různé operátory. Funkce je rovněž zpětně kompatibilní, proto vaše staré požadavky budou fungovat i nadále a budou vracet stejné výsledky jako dříve.

K filtraci můžete využít celkem 9 operátorů:

  • eq – is equal (je rovno, přesná shoda)
  • !eq – is not equal (není rovno, liší se)
  • gt – greater than (větší než)
  • lt – less than (menší než)
  • ct – contains (obsahuje)
  • set  – is set (je nastaveno)
  • !set – is not set (není nastaveno)
  • true – hodnota boolového atributu je true
  • false – hodnota boolového atributu je false

Nové operátory lze využít u sloupců, které jsou typu string (texty), number (čísla), boolean (ano / ne), date (datum) a datetime (datum a čas). Platí, že pro daný datový typ lze použít vždy pouze některé z definovaných operátorů:

  • string – eq, !eq, ct, set, !set
  • number- eq, !eq, gt, lt, set, !set
  • boolean – set, !set, true, false
  • date – eq, !eq, gt, lt, set, !set
  • datetime – eq, !eq, gt, lt, set, !set

Přejděme rovnou na příklad, kdy máme v systému kontakty se strukturou dat podobnou této:

Contact {
  string firstName,
  string lastName,
  string email,
  lastorderdate date,
  orderscount int,
  isenabled bool
}

FirstName, lastName a email jsou systémové sloupce, lastorderdate, orderscount a isenabled jsou uživatelské sloupce. Rádi bychom získali kontakty, které mají e-mail na seznamu, datum poslední objednávky je před 1. 9. 2023, mají více než 3 objednávky a jsou povolené. Výsledný požadavek URI bude vypadat takto:

https://api.boldem.cz/v1/contacts?filter=email~ct~seznam.cz|lastorderdate~lt~2023-09-01|orderscount~gt~3|isenabled~true

Jednotlivé položky filtru jsou odděleny znakem svislé čáry |. Každá položka filtru se může skládat ze 2 až 3 části oddělených znakem vlnovky ~. Pokud se skládá ze tří částí, první část je identifikátor sloupce, druhá je operátor a třetí je hodnota filtru. Pokud se skládá ze 2 částí, první část je identifikátor sloupce a druhá je buď operátor, který nevyžaduje hodnotu filtru (set, !set atd.) nebo hodnota. V tomto případě se jako operator použije eq.

Filtry s operátorem lze samozřejmě kombinovat s parametry sort a include, například voláním:

https://api.boldem.cz/v1/contacts?filter=email~ct~seznam.cz|lastorderdate~lt~2023-09-01|orderscount~gt~3|isenabled~true&sort=contactId~desc&include=customColumns

získáme výše definované kontakty seřazené od nejnovějších a v odpovědi budeme ke každému kontaktu mít navíc informace o jeho uživatelských sloupcích.

Kompletní dokumentaci k API najdete na https://api.boldem.cz/