Obecný formát dotazu s filtry
Sestavení requestu s filtrem na řádky i sloupce (obecná syntaxe):
GET http(s)://[adresa API]/[Endpoint]?FILTER_CLAUSE&SELECT_CLAUSE
České znaky
Pokud hodnota (textové) property použitá v podmínce filtru obsahuje české znaky (obecně jakékoli znaky s diakritikou), je nutno takovouto hodnotu enkódovat dle následující tabulky (sloupec v UTF-8).
Operátory
Každý z operátorů je funkční jen pro atributy určitých datových typů – viz následující tabulka (ozn. x).
| Operátor | REST API v1.0 | REST API v2.0 | GraphQL | Textová hodnota | Číselná hodnota | Logická hodnota | Datum |
| rovná se | Equal | eq | eq | x | x | x | x |
| nerovná se | NotEqual | ne | ne | x | x | x | x |
| méně než | Less | lt | lt | – | x | – | x |
| méně než / rovno | LessEqual | lte | lte | – | x | – | x |
| větší než | Greater | gt | gt | – | x | – | x |
| větší než / rovno | GreaterEqual | gte | gte | – | x | – | x |
| začíná na | StartWith | sw | sw | x | – | – | – |
| obsahuje | Contains | ct | ct | x | – | – | – |
| končí na | EndWith | ew | ew | x | – | – | – |
Vlastnosti typu enum je možné filtrovat i na základě textové hodnoty,
např.: movementType~eq~Received je ekvivalentní s movementType~eq~1
Třídění
(REST) API v1.0
GET http(s)://[adresa API]/Company?order.OrderProperties[0].PropertyName=ObchNazev&order.OrderProperties[0].Direction=asc
GET http://demo.moneys5.cz:81/Company?order.OrderProperties[0].PropertyName=ObchNazev&order.OrderProperties[0].Direction=asc
(REST) API v2.0
GET http(s)://[adresa API]/v2.0/Company?order=ObchNazev~asc
Směr třídění
asc vzestupně
desc sestupně
GET http://demo.moneys5.cz:81/v2.0/Company?order=ObchNazev~asc
Filtrování řádků (WHERE) – FILTER_CLAUSE
(REST) API v1.0
Jednoduchý filtr:
GET http(s)://[adresa API]/ReceivedOrder?filter.PropertyName=SumaCelkemCM&filter.Operation=Equal&filter.ExpectedValue=6037,90
GET http://demo.moneys5.cz:81/ReceivedOrder?filter.PropertyName=SumaCelkemCM&filter.Operation=Equal&filter.ExpectedValue=6037,90
Kombinovaný filtr (pole jednoduchých filtrů):
GET http(s)://[adresa API]/ReceivedOrder?filter.Filters[0].PropertyName=SumaCelkemCM&filter.Filters[0].Operation=GreaterEqual&filter.Filters[0].ExpectedValue=1000&filter.LogicOperator=AND&filter.Filters[1].PropertyName=SumaCelkemCM&filter.Filters[1].Operation=LessEqual&filter.Filters[1].ExpectedValue=4000
GET http://demo.moneys5.cz:81/ReceivedOrder?filter.Filters[0].PropertyName=SumaCelkemCM&filter.Filters[0].Operation=GreaterEqual&filter.Filters[0].ExpectedValue=1000&filter.LogicOperator=AND&filter.Filters[1].PropertyName=SumaCelkemCM&filter.Filters[1].Operation=LessEqual&filter.Filters[1].ExpectedValue=4000
Složený filtr (pole jednoduchých a kombinovaných filtrů):
GET http(s)://[adresa API]/ReceivedOrder?filter.Filters[0].PropertyName=Faze&filter.Filters[0].Operation=Equal&filter.Filters[0].ExpectedValue=1&filter.LogicOperator=AND&filter.InnerLogics[0].Filters[0].PropertyName=Zakazka_ID&filter.InnerLogics[0].Filters[0].Operation=Equal&filter.InnerLogics[0].Filters[0].ExpectedValue=af2b8c86-1fce-4816-a93e-2a7201a73df3&filter.InnerLogics[0].Filters[1].PropertyName=Zakazka_ID&filter.InnerLogics[0].Filters[1].Operation=Equal&filter.InnerLogics[0].Filters[1].ExpectedValue=9c06a988-9345-44a2-9e5e-e46a828d3cd7&filter.InnerLogics[0].LogicOperator=OR
GET http://demo.moneys5.cz:81/ReceivedOrder?filter.Filters[0].PropertyName=Faze&filter.Filters[0].Operation=Equal&filter.Filters[0].ExpectedValue=1&filter.LogicOperator=AND&filter.InnerLogics[0].Filters[0].PropertyName=Zakazka_ID&filter.InnerLogics[0].Filters[0].Operation=Equal&filter.InnerLogics[0].Filters[0].ExpectedValue=af2b8c86-1fce-4816-a93e-2a7201a73df3&filter.InnerLogics[0].Filters[1].PropertyName=Zakazka_ID&filter.InnerLogics[0].Filters[1].Operation=Equal&filter.InnerLogics[0].Filters[1].ExpectedValue=9c06a988-9345-44a2-9e5e-e46a828d3cd7&filter.InnerLogics[0].LogicOperator=OR
(REST) API v2.0
Jednoduchý filtr:
GET http(s)://[adresa API]/v2.0/Company?filter=ID~eq~d86fffe9-b2c6-4089-910c-17aba0952290
GET http://demo.moneys5.cz:81/v2.0/Company?filter=ID~eq~d86fffe9-b2c6-4089-910c-17aba0952290
Jednoduchý filtr (filtrovaná hodnota obsahuje mezery):
GET http(s)://[adresa API]/v2.0/Company?filter=Nazev~eq~Byznys%20software,%20s.r.o.
GET http://demo.moneys5.cz:81/v2.0/Company?filter=Nazev~eq~Byznys%20software,%20s.r.o.
Jednoduchý filtr (filtrování dle atributu typu datum):
GET http(s)://[adresa API]/v2.0/JobOrder?filter=DatumPlanovanehoZahajeni~eq~2022-02-22
GET http://demo.moneys5.cz:81/v2.0/JobOrder?filter=DatumPlanovanehoZahajeni~eq~2022-02-22
Kombinovaný filtr (pole jednoduchých filtrů) [operátor AND]:
GET http(s)://[adresa API]/v2.0/ReceivedOrder?filter=SumaCelkemCM~gte~1000#SumaCelkemCM~lte~4000
GET http://demo.moneys5.cz:81/v2.0/ReceivedOrder?filter=SumaCelkemCM~gte~1000#SumaCelkemCM~lte~4000
Kombinovaný filtr (pole jednoduchých filtrů) [operátor OR]:
GET http(s)://[adresa API]/v2.0/ReceivedOrder?filter=SumaCelkemCM~lte~1000|SumaCelkemCM~gte~4000
GET http(s)://[adresa API]/v2.0/ReceivedOrder?filter=SumaCelkemCM~lte~1000|SumaCelkemCM~gte~4000
Filtrování sloupců (SELECT) – SELECT_CLAUSE
(REST) API v1.0
Úplná syntaxe:
GET http(s)://[adresa API]/IssuedInvoice?select.Properties[0]=ID&select.Properties[1]=CisloDokladu&select.Properties[2]=Nazev
Zkrácená syntaxe:
GET http(s)://[adresa API]/IssuedInvoice?select.Properties=ID,CisloDokladu,Nazev
GET http://demo.moneys5.cz:81/IssuedInvoice?select.Properties=ID,CisloDokladu,Nazev
(REST) API v2.0
GET http(s)://[adresa API]/v2.0/IssuedInvoice?select=ID,CisloDokladu,Nazev
GET http://demo.moneys5.cz:81/v2.0/IssuedInvoice?select=ID,CisloDokladu,Nazev
Filtrování sloupců je funkční i pro metody (endpointy) s omezeným počtem záznamů:
GET http(s)://[adresa API]/v2.0/IssuedInvoice/0/100?select=ID,CisloDokladu,Nazev
GET http://demo.moneys5.cz:81/v2.0/IssuedInvoice/0/100?select=ID,CisloDokladu,Nazev
Filtrování sloupců není funkční pro metody (endpointy) pro konkrétní záznam (/{id}) => řeší se to zasláním dotazu na obecný endpoint s aplikovaným filtrem na pole ID:
GET http(s)://[adresa API]/v2.0/IssuedInvoice?filter=ID~eq~c47ac22e-38fb-48d8-ae30-47b39290d49e&select=ID,CisloDokladu,Nazev
GET http://demo.moneys5.cz:81/v2.0/IssuedInvoice?filter=ID~eq~c47ac22e-38fb-48d8-ae30-47b39290d49e&select=ID,CisloDokladu,Nazev
Vrácené záznamy
(REST) API v1.0
Filtr na existující hodnotu dané property
GET http(s)://[adresa API]/Article/0/1000?select.Properties=Nazev,Kod,Katalog,TypArtiklu,Zaruka_Typ,Zaruka_Doba,DodaciLhuta_Typ,DodaciLhuta_Doba,ID&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=3466d27d-7381-4464-a97b-d49e1c355465
GET http://demo.moneys5.cz:81/Article/0/1000?select.Properties=Nazev,Kod,Katalog,TypArtiklu,Zaruka_Typ, Zaruka_Doba,DodaciLhuta_Typ,DodaciLhuta_Doba,ID&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=3466d27d-7381-4464-a97b-d49e1c355465
API vrátí pouze daný záznam:
Filtr na neexistující hodnotu dané property
GET http(s)://[adresa API]/Article?select.Properties=Nazev,Kod,Katalog&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=efa349d7-bccd-4d2a-8dc8-60d3cba72984
GET http://demo.moneys5.cz:81/Article?select.Properties=Nazev,Kod,Katalog&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=efa349d7-bccd-4d2a-8dc8-60d3cba72984
Filtr na nevalidní hodnotu dané property
GET http(s)://[adresa API]/Article?select.Properties=ID,Nazev,Kod,Katalog&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=Autobus
Pozn. očekávanou hodnotu (ExpectedValue) nelze implicitně převést na požadovaný datový typ
API vrátí všechny záznamy, protože požadovaný filtr nelze korektně sestavit, tzn. provede se select dat bez aplikovaného filtru.
GET http://demo.moneys5.cz:81/Article?select.Properties=ID,Nazev,Kod,Katalog&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=Autobus
Filtr na prázdnou (neuvedenou) hodnotu dané property
GET http(s)://[adresa API]/Article?select.Properties=ID,Nazev,Kod,Katalog&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=
API vrátí záznamy vyhovující podmínce [PropertyName] IS NULL.
GET http://demo.moneys5.cz:81/Article?select.Properties=ID,Nazev,Kod,Katalog&filter.PropertyName=ID&filter.Operation=Equal&filter.ExpectedValue=
Filtr na neexistující property
GET http(s)://[adresa API]/Article?select.Properties=ID,Nazev,Kod,Katalog&filter.PropertyName=Akce&filter.Operation=Equal&filter.ExpectedValue=1
Pozn. daný objekt neobsahuje property (PropertyName), přes kterou se provádí filtrování
API vrátí všechny záznamy, protož požadovaný filtr nelze korektně sestavit, tzn. provede se select dat bez aplikovaného filtru.
GET http://demo.moneys5.cz:81/Article?select.Properties=ID,Nazev,Kod,Katalog&filter.PropertyName=Akce&filter.Operation=Equal&filter.ExpectedValue=1
Omezení délky (složitosti) filtru
Maximální délka URL adresy i maximální délka parametrů dotazu (path) jsou na straně IIS omezeny. Pokud je použitý filtr složený z mnoha podmínek, může se stát, že jeho délka překročí dané omezení a takovýto request skončí chybou, např. 414 URI Too Long.
Toto nastavení lze v IIS upravit: Weby -> [web API] -> Filtrování požadavků -> Upravit nastavení funkcí
Swagger dokumentace z našeho demo serveru je dostupná na http://demo.moneys5.cz:81/swaggerDoc/. Pro údaje ClientID a ClientSecret si zažádejte pomocí formuláře.