5.14.3 api dir update

Funkce /api/dir/update umožňuje aktualizaci pole záznamů v adresáři a nastavení jejich vybraných polí.

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 zobrazení najdete v kapitole api/dir/template.


Tabulka 1. Klíče požadavku JSON
Název klíčePovinnýOčekávané hodnotyVýchozí hodnotaPopis

users

Ano

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

-

Pole musí obsahovat nejméně jeden objekt s klíčem uuid, který definuje, který záznam se má aktualizovat.

Přehled dostupných klíčů v 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/update JSON { "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@def.cz", "access": { "pin": "1234" } }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654", "name": "ABCD2", "owner": "My2N", "email": "abcd2@def.cz" }, { "uuid": "01234567-89A-CDEF-0123-456789ABCDEF", "name": "ABCD3", "owner": "My2N", "email": "abcd3@def.cz" }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD4", "owner": "My2N", "email": "abcd4@def.cz", "albert": "einstein" }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD4", "owner": "My2N", "email": "abcd4@def.cz", "access.pin": "hello" } ] }

Pokud není v adresáři žádný záznam s uuid 01234567-89AB-CDEF-0123-456789ABCDEF, zařízení odpoví chybovým kódem (viz dále). To samé platí pro druhý uuid 76543210-68FF-18CA-3210-FEDCBA987654.


Jestliže je v adresáři záznam s uuid 01234567-89AB-CDEF-0123-456789ABCDEF, budou jeho parametry aktualizovány podle hodnot zadaných pro jednotlivé klíče. To samé platí pro druhý uuid 76543210-68FF-18CA-3210-FEDCBA987654.

Třetí záznam nebude aktualizován (uuid má špatný formát).


Čtvrtý záznam nebude aktualizován (neznámý název pole).


Pátý záznam nebude aktualizován (nesprávný formát přístupového PINu).


Odpověď

Odpověď je ve formátu application/json. Objekt 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é hodnotyPopis

uuid

uuid

Unikátní uživatelský identifikátor (Unique User Identifier) upraveného nebo nezměněného zápisu.

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_DOES_NOT_EXIST - záznam s daným uuid neexistuje (tj. nedá se aktualizovat).

  • EDIR_UUID_IS_MISSING - chybí povinný klíč uuid.

  • 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_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_PHOTO - byl dosažen maximální počet fotografií v úložišti. Další fotografie se nedají přidávat.

  • EDIRLIM_FPT - byl dosažen maximální počet šablon otisků prstů v úložišti. Další otisky prstů se nedají přidávat.

  • 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": 39 }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654", "errors": [ { "code": "EDIR_UUID_DOES_NOT_EXIST" } ] }, { "uuid": "01234567-89A-CDEF-0123-456789ABCDEF", "errors": [ { "code": "EDIR_UUID_INVALID_FORMAT" } ] }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "errors": [ { "code": "EDIR_FIELD_NAME_UNKNOWN", "field": "albert" } ] }, { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "errors": [ { "code": "EDIR_FIELD_VALUE_ERROR", "field": "access.pin" } ] } ] } }

První záznam v adresáři je úspěšně aktualizován, vrátí se jeho uuid a timestamp změny.


Druhý záznam neexistuje (není záznam s tímto uuid).


Třetí objekt má špatný formát uuid.


Ve čtvrtém objektu je uveden neznámý klíč albert.


V pátém objektu je zadána nesprávná hodnota PIN kódu.