5.14.2 api dir create

Funkce /api/dir/create umožňuje vytvářet (nebo přepisovat) pole záznamů v adresáři a nastavovat jejich vybraná pole.

Skupiny služeb a privilegií

Služba je System.
Privilegia jsou Systém – řízení.

Metody

PUT

Požadavek

Požadavek obsahuje parametry ve formátu application/json. Více informací o jednotlivých parametrech záznamu v adresáři a jejich objektovém zobrazení najdete v kapitole api/dir/template.

Tabulka 1. Klíče požadavku JSON

Název klíče Povinný Očekávané hodnoty Výchozí hodnota Popis

force

Ne

true, false

false

Tento klíč vybírá, zda bude záznam v adresáři identifikovaný daným uuid (viz níže) přepsán novou sadou dat.

Když bude hodnota tohoto klíče nastavena na true, přepíší se existující data novou sadou dat a zbylá pole budou nastavena na výchozí hodnoty.

Když bude nastavena na false nebo vynechána (omitted) a v adresáři existuje záznam s daným uuid, zařízení odpoví chybovým kódem EDIR_UUID_ALREADY_EXISTS a změny konfigurace nebudou provedeny.

Tento klíč nijak neovlivňuje vytvoření nového záznamu v adresáři.

users

Ne

pole JSON objektů definujících parametry záznamu v adresáři

-

Jestliže je klíč vynechán nebo jeho hodnota je prázdné pole, odpověď zařízení obsahuje pouze klíč series (nevytvoří se nové záznamy v adresáři).

Do pole je možné zadávat prázdné objekty. Zařízení vytvoří pro každý prázdný objekt prázdný záznam v adresáři (pouze s přiřazeným identifikátorem uuid).

Jestliže nějaký objekt v poli obsahuje klíč uuid, vytvoří se nebo změní záznam s daným uuid nebo zařízení odpoví chybovým kódem.

Jestliže nějaký objekt v poli neobsahuje uuid, zařízení vytvoří nový záznam a přiřadí mu nový identifikátor uuid. Parametry záznamu jsou nastaveny na hodnoty podle klíčů definovaných v JSON struktuře požadavku. Viz příklad dole.

Přehled všech dostupných klíčů ve JSON definici záznamu v adresáři najdete v kapitole api/dir/template.

Příklad požadavku

URL: https://192.168.1.1/api/dir/create JSON { "force": true, "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@def.cz", "access": { "pin": "1234" } }, { "name": "ABCD2", "owner": "My2N", "email": "abcd2@def.cz" }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD3", "email": "something", "access": { "pin": "5678" }, "test": "something", "albert": "einstein" }, {}, {} ] }

Pokud v adresáři není žádný záznam s uuid 01234567-89AB-CDEF-0123-456789ABCDEF, zařízení vytvoří záznam s tímto identifikátorem a nastaví název jeho parametrů, e-mail a přístup na zadané hodnoty.

Je-li v adresáři záznam s uuid 01234567-89AB-CDEF-0123-456789ABCDEF, zařízení přepíše název jeho parametrů, e-mail a přístup na zadané hodnoty a všechny jeho ostatní parametry nastaví na výchozí hodnoty (protože parametr klíče force je nastaven na true).

Zařízení vytvoří druhý záznam, přiřadí mu náhodný identifikátor uuid, nastaví jeho název, vlastníka a e-mail na zadané hodnoty a zbylým parametrům ponechá výchozí hodnoty.

Třetí záznam nepřepíše stávající záznam se stejným uuid, protože je tam několik chyb (e-mail má nesprávný formát, jsou tam neexistující pole s názvem test a albert).

Navíc se vytvoří dva prázdné nové záznamy (protože jsou v poli dva prázdné objekty). Každému z nich je přidělen náhodný identifikátor uuid, zbylé parametry jsou nastaveny na výchozí hodnoty.

Odpověď

Odpověď je ve formátu application/json. Výsledek (result) obsahuje klíče series a users.

Více informací o použití klíče series najdete v kapitole api/dir/query.

Klíč users obsahuje pole objektů, které obsahují klíče a hodnoty z výsledku požadavku (viz následující tabulka).

Tip

Více o struktuře JSON odpovědi se dozvíte z příkladu na konci této kapitoly.

Tabulka 2. Klíče JSON odpovědi v poli users

Klíč	Typické vrácené hodnoty	Popis
uuid	uuid	Unikátní uživatelský identifikátor (Unique User Identifier) vytvořeného, upraveného nebo nezměněného záznamu.
timestamp	celé číslo	Časová značka změn provedených v adresáři. Více informací o použití časové značky najdete v kapitole api/dir/query. Časová značka je uvedena, jen když je změna v adresáři provedena úspěšně.
errors	pole chybových objektů	Chybový objekt obsahující pole všech chyb, které nastaly. Objekt errors je uveden, jen když se změnu v adresáři nepodařilo provést. V hodnotě klíče code je obsažen chybový kód, který ukazuje důvod neúspěšného provedení změny v adresáři. Další zpřesnění důvodu chyby může být v hodnotě klíče field pro chybové kódy `EDIR_FIELD_NAME_UNKNOWN` a `EDIR_FIELD_VALUE_ERROR`, identifikující klíč nebo hodnotu nesplňující validační pravidla. V odpovědi se mohou vrátit následující chybové kódy: `EDIR_UUID_INVALID_FORMAT` - uuid nemá platný formát, který je "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", kde X může být jakákoli hexadecimální číslice. Všechny nuly jsou rezervovány pro prázdný uuid. `EDIR_UUID_ALREADY_EXISTS` - v adresáři existuje záznam se zadaným identifikátorem uuid a klíč force je nastaven na false nebo omitted. Požadovaná změna proto nemůže být provedena. `EDIR_FIELD_NAME_UNKNOWN` - neznámý klíč. Seznam dostupných klíčů pro dané zařízení najdete v kapitole /api/dir/template. `EDIR_FIELD_VALUE_ERROR` - zadaná hodnota nesplňuje validační kritéria (hodnota není platná). `EDIRLIM_USER` - adresář je plný. `EDIRLIM_PHOTO` - byl dosažen maximální počet fotografií v úložišti. Nové záznamy mohou být vytvořeny jen bez fotografií. `EDIRLIM_FPT` - byl dosažen maximální počet šablon otisků prstů v úložišti. Nové záznamy mohou být vytvořeny jen bez otisků prstů. `EINCONSISTENT` - v hodnotách klíčů validFrom a validTo je nesrovnalost (validFrom musí být menší než validTo).

Příklad odpovědi

{ "success": true, "result": { "series": "6423407687606431951", "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "timestamp": 34 }, { "uuid": "044197A7-54AD-7577-6EEA-787A6097263E", "timestamp": 35 }, { "errors": [ { "code": "EDIR_FIELD_VALUE_ERROR", "field": "email" }, { "code": "EDIR_FIELD_NAME_UNKNOWN", "field": "test" }, { "code": "EDIR_FIELD_NAME_UNKNOWN", "field": "albert" } ] }, { "uuid": "41970B83-21C8-45DD-8FFC-787A6097263E", "timestamp": 36 }, { "uuid": "0447BBA7-6E7c-420C-A654-466D43D6A067", "timestamp": 37 } ] } }

První záznam je vytvořen se zadaným identifikátorem uuid a zadanými poli (nezadaná pole jsou nastavena na výchozí hodnoty). Záznam se vytvoří bez ohledu na existenci záznamu se stejným uuid, protože klíč force je v požadavku nastaven na true. Vrátí se časová značka změny.

Druhý záznam je vytvořen s náhodným uuid a jsou vyplněna zadaná pole (nezadaná pole jsou nastavena na výchozí hodnoty). Vrátí se časová značka změny.

Třetí objekt v požadavku obsahoval neplatný formát e-mailové adresy. Navíc klíče test a albert odkazovaly k neexistujícím polím.

Vytvoření čtvrtého a pátého záznamu proběhlo úspěšně s náhodně přiřazeným identifikátorem uuid a všechna pole byla nastavena na výchozí hodnoty. Časová značka v zařízení se tudíž dvakrát aktualizovala. Vrátí se časové značky změn.

Tip

Jestliže klíč force v požadavku není nastaven na true, všechny pokusy o vytvoření záznamu se stávajícím uuid skončí chybovým kódem EDIR_UUID_ALREADY_EXISTS.