Základní funkce API

API poskytuje webové rozhraní s několika základními funkcemi/URL. Pomocí přístupu k aplikační databázi načte požadovaná data a pošle je přes HTTP(S) protokol klientovi ve formátu JSON. testovací změna.

Formát URL adresy

Všechny funkce API mají formát URL adresy. Adresa sestává z fixní části a z části s parametry. Parametry určují, jaká data se budou z ESO9 získávat, popř. dále upřesňují jejich rozsah.

V případě, že se v URL parametrech vyskytují nepřípustné znaky, je třeba je převést tzv. URL encodingem. Viz např. urlencoder.org.

Zabezpečení

Všechny funkce API (tj. URL adresy) jsou zabezpečeny Basic Authentication. Jméno a heslo se nastavují v konfiguračním souboru, viz kapitola Instalace a konfigurace.

Formát dat

Všechny funkce API vrací data ve formátu JSON. Tento formát umí zpracovat všechny nástroje pro datovou analýzu či vizualizaci, ale i např. databázové systémy typu MS SQL Server.

Kořenovým elementem je vždy název požadované tabulky nebo pohledu. Jednotlivé záznamy jsou ve formátu jednorozměrného pole.

Příklad (první 2 záznamy z tabulky SUBJEKT):

{
    "subjekt": [
        {
            "IDSUBJEKT": 208,
            "KOD_SUBJEKTU": "0028",
            "ICO": "00006912",
            "DIC": "CZ00006912",
            "SUBJ_NAZEV": "Finanční úřad",
            "IDSUBJADR": 295,
            "IDSUBJOSOBA": 323,
            "IDSUBJBUCET": 160,
            "VLSTAVSUBJEKT": 0,
            "VLSUBJ_KONSOLIDACE": 0,
            "VLSUBJTYPSPOL": 0,
            "VLSUBJOBRAT": 0,
            "VLSUBJPOCETZAM": 0,
            "VLPRAVNIFORMA": 14,
            "IDUZIVATEL_UPDATE": 327,
            "DTUPDATE": "2018-12-17T14:53:37",
            "VLPLATCEDPH": 0,
            "VLNEDUVERYHODNYPLATCE": -1
        },
        {
            "IDSUBJEKT": 219,
            "KOD_SUBJEKTU": "0001",
            "ICO": "27624609",
            "DIC": "CZ27624609",
            "SUBJ_NAZEV": "ESO9 international a.s.",
            "IDSUBJADR": 365,
            "IDSUBJOSOBA": 335,
            "IDSUBJBUCET": 188,
            "SUBJ_POZNAMKA": "Informační systémy ESO9",
            "VLSTAVSUBJEKT": 0,
            "SUBJEKT_WEBSITE": "www.eso9.cz",
            "VLPRAVNIFORMA": 1,
            "DATOVASCHRANKAID": "czxfpqh",
            "VLPLATCEDPH": 2,
            "VLNEDUVERYHODNYPLATCE": 0
        }
    ]
}

Přehled funkcí

Funkce	Metoda	Popis
getData	`GET`	Vrací všechna data z tabulky/pohledu
getDataWithCondition	`GET`	Vrací data omezená podmínkou
getRowsCount	`GET`	Vrací počet řádků
getDataPaginate	`GET`	Vrací stránkovaná data
getFile	`GET`	Stáhne soubor z DMS
setFile	`POST`	Nahraje soubor do DMS

Funkce getData

Vrací všechna data z dané tabulky nebo pohledu bez omezení.

URL:

https://{Server}/JsonAPI/Data/getData/{DataSource}

Parametr	Popis
`{Server}`	Jméno webového serveru, který hostuje API
`{DataSource}`	Jméno tabulky nebo pohledu z ESO9, jehož data funkce vrací

Pokud používáme pro uživatelský účet přistupující k aplikační databázi oprávnění pro čtení, není třeba nic dále nastavovat. Pokud používáme oprávnění pouze pro vybrané databázové objekty, je třeba každému takovému objektu (tabulce, pohledu) nastavit oprávnění Select.

Příklad:

https://api.eso9.cz/JsonAPI/Data/getData/QSUBJEKT

Příklad vrátí všechna data z pohledu QSUBJEKT, tj. informace o subjektech (obchodních partnerech).

Funkce getDataWithCondition

Vrací data z dané tabulky nebo pohledu omezená zadanou podmínkou.

URL:

https://{Server}/JsonAPI/Data/getDataWithCondition/{DataSource}?{Condition}

Parametr	Popis
`{DataSource}`	Jméno tabulky nebo pohledu z ESO9, jehož data funkce vrací
`{Condition}`	Podmínka ve tvaru `condition=SQL_where_condition` (syntaxe T-SQL WHERE)

Příklad:

https://api.eso9.cz/JsonAPI/Data/getDataWithCondition/QHDOK_FAV?condition=UCET_OBD%3E%272020.01%27

Příklad vrátí data z pohledu QHDOK_FAV (tj. vydané faktury) omezená na účetní období větší než 2020.01 (UCET_OBD>'2020.01'). Nepřípustné znaky v URL jsou převedené URL encodingem.

Funkce getRowsCount

Vrací počet řádků tabulky nebo pohledu.

URL:

https://{Server}/JsonAPI/Data/getRowsCount/{DataSource}

Parametr	Popis
`{DataSource}`	Jméno tabulky nebo pohledu z ESO9, počet jehož řádků funkce vrací

Příklad:

https://api.eso9.cz/JsonAPI/Data/getRowsCount/PSC

Příklad vrátí počet řádků tabulky s PSČ.

Funkce getDataPaginate

Vrací stránkovaná data z tabulky nebo pohledu. Stránku s daty určuje její počátek a velikost. Funkce je určena pro postupné načítání rozsáhlých dat. Pro provoz v kontejneru jediný způsob, jak postupně načíst rozsáhlejší data.

URL:

https://{Server}/JsonAPI/Data/getDataPaginate/{DataSource}?fromRow=x&rows=y

Parametr	Popis
`{DataSource}`	Jméno tabulky nebo pohledu z ESO9, jehož data funkce vrací
`fromRow`	Číslo řádku, odkud se mají data číst
`rows`	Počet řádků, které má funkce vrátit

Příklad:

https://api.eso9.cz/JsonAPI/Data/getDataPaginate/PSC?fromRow=2000&rows=300

Příklad vrátí 300 řádků tabulky s PSČ počínaje řádkem č. 2000.

Funkce getFile

Vrací soubor z DMS na základě jeho unikátního identifikátoru GUID.

URL:

https://{Server}/JsonAPI/File/getFile/{fileGUID}

Parametr	Popis
`{fileGUID}`	Identifikátor (GUID) souboru z DMS ESO9, který chceme stáhnout

Příklad:

https://api.eso9.cz/JsonAPI/File/getFile/44C985A2-48F1-4DE0-8B2C-8CFD314E1747

Příklad vrátí soubor s daným GUID identifikátorem.

Funkce setFile

Uloží soubor do DMS a spustí nad ním uživatelskou proceduru. Na rozdíl od všech předchozích funkcí se nejedná o čtení dat (HTTP GET), ale o zápis (HTTP POST).

Soubor se zakládá pouze do dokumentové databáze do tabulky ESO9DOC; k souboru se tedy nezakládá záznam do aplikační databáze (do navázané tabulky DOKUMENT). Mechanismus je určen primárně pro jednoduché souborové importy, kdy po zpracování obsahu souboru tento zrušíme.

Nastavení oprávnění

Protože funkce zapisuje do DMS ESO9, je třeba Windows účtu (resp. SQL účtu), pod nímž API přistupuje k dokumentové databázi, nastavit minimálně role db_datareader a db_datawriter.

Pokud se po uložení souboru volá uživatelská procedura, je třeba příslušné roli nastavit k této proceduře oprávnění Execute.

Upload souboru

Pro upload souboru do DMS se používá formát MultiPart Form Data. Soubor se odesílá v těle HTTP requestu, zatímco případné další parametry se posílají na URL. V těle requestu je povinná jediná MultiPart část s názvem file.

URL:

https://{Server}/JsonAPI/File/setFile?userDBProcedure={spProcedure}

Parametr	Popis
`{spProcedure}`	Jméno uživatelské procedury (nepovinné), která se zavolá po úspěšném uložení souboru. Jediným vstupním parametrem je GUID souboru.

Příklad uživatelské procedury:

/*
  Procedura volaná PO importu souboru do DMS přes JSON API
*/
CREATE OR ALTER PROCEDURE dbo.spUploadFile
  @FILEGUID  uniqueidentifier
AS
  Set Nocount ON
    -- výkonná část procedury
  RETURN 0
GO

Příklad HTTP requestu:

POST /Data/setFile?userDBProcedure=spUploadFile HTTP/1.1
Authorization: Basic RVNPOUV4Y2VsQVBJOkhlc2xvMTIz
Content-Type: multipart/form-data; boundary=---boundary123

-----boundary123
Content-Disposition: form-data; name="file"; filename="Invoice2021_346.pdf"
<binární obsah souboru>
-----boundary123--

Struktura MultiPart requestů je popsána např. na swagger.io.

Automatizace volání s cURL

cURL je řádková utilita pro přenos dat z/na server pomocí protokolu HTTP. Pomocí tohoto nástroje lze jednoduše zavolat jakékoli webové API.

tip

U metod typu GET s výstupem ve formátu JSON je zpravidla lepší použít jako klienta MS Excel (viz Napojení na MS Excel).

Příklad – import souboru

Upload a import souboru z příkazové řádky (volá API funkci setFile na serveru Win2019, po uploadu souboru API.pdf spustí uživatelskou proceduru spUploadFile):

curl -X POST "https://win2019/ESO9JsonAPI/File/setFile?userDBProcedure=spUploadFile" \
  --user ESO9ExcelAPI:Heslo123 \
  -H "accept: */*" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@API.pdf;type=application/pdf" \
  --insecure

Příklad – hromadné stažení souborů z DMS

Automatické stažení více souborů z DMS z příkazové řádky pomocí skriptu v PowerShellu. Předpokládejme, že seznam souborů ke stažení máme definovaný v pohledu QDOKUMENTOBR:

###################################################################
# Stažení souborů z příkazové řádky z aplikace ESO9 pomocí JSON API
###################################################################

# Definice proměnných
$username = "ESO9ExcelAPI"
$password = "Heslo123"
$baseDirectory = "c:\Temp\curl-8.3.0_1-win64-mingw\bin\"
$outputFile = "$baseDirectory\FILE.jpg"

# Dočasné umístění pro JSON soubor s odpovědí ze serveru
$jsonFile = "$baseDirectory\response.json"

# Stažení JSON dat
$url = "https://win2019-tu2/ESO9JSONAPI/Data/getData/QDOKUMENTOBR"
$curlCommand = "curl.exe -X GET `"$url`" --user `"$username`:$password`" --header `"Accept: */*`" -o `"$jsonFile`" --insecure"
Invoke-Expression $curlCommand

# Čtení a parsování JSON souboru
$jsonData = Get-Content -Raw -Path $jsonFile | ConvertFrom-Json

# Cyklus přes všechny soubory ke stažení
$url = "https://win2019-tu2/ESO9JSONAPI/File/getFile"

foreach ($doc in $jsonData.QDOKUMENTOBR) {
    $fileGuid = $doc.DOKUMENTFILEGUID
    $fileName = $doc.FILENAME

    # Sestavení URL pro stažení jednoho souboru
    $downloadUrl = "$url/$fileGuid"

    # Cesta k uložení jednoho souboru
    $outputFile = "$baseDirectory\$fileName"

    # Stažení souboru pomocí cURL
    $curlDownloadCommand = "curl.exe -X GET `"$downloadUrl`" --user `"$username`:$password`" --header `"Accept: */*`" -o `"$outputFile`" --insecure"
    Write-Output "File URL: $downloadUrl"
    Invoke-Expression $curlDownloadCommand

    Write-Output "Downloaded: $fileName"
}

Formát URL adresy​

Zabezpečení​

Formát dat​

Přehled funkcí​

Funkce getData​

Funkce getDataWithCondition​

Funkce getRowsCount​

Funkce getDataPaginate​

Funkce getFile​

Funkce setFile​

Nastavení oprávnění​

Upload souboru​

Automatizace volání s cURL​

Příklad – import souboru​

Příklad – hromadné stažení souborů z DMS​

Formát URL adresy

Zabezpečení

Formát dat

Přehled funkcí

Funkce getData

Funkce getDataWithCondition

Funkce getRowsCount

Funkce getDataPaginate

Funkce getFile

Funkce setFile

Nastavení oprávnění

Upload souboru

Automatizace volání s cURL

Příklad – import souboru

Příklad – hromadné stažení souborů z DMS