5.14.5 api dir get

Funkce /api/dir/get slouží k vyhledávání pole záznamů v adresáři a jejich zadaných polí.


Skupiny služeb a privilegií

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

Metody

  • POST


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íčePovinnýOčekávané hodnotyVýchozí hodnotaPopis

fields

Ne

pole řetězců

všechna pole s jinými hodnotami než výchozími

V odpovědi musí být specifikována jména požadovaných polí, pokud ne, vrátí se všechna pole s nevýchozími hodnotami, pokud se zadá prázdné pole, vrátí se všechna dostupná pole. Přehled všech dostupných klíčů v JSON definici záznamu v adresáři najdete v kapitole api/dir/template. Neznámé názvy polí budou ignorovány.

users

Ne

pole JSON objektů definujících uuid

-

Pole musí obsahovat alespoň jeden objekt s klíčem uuid, který definuje záznam, jehož pole se mají vrátit. Pokud klíč chybí nebo je zadáno prázdné pole, vrátí se prázdné pole.


Příklad požadavku

URL: https://192.168.1.1/api/dir/get JSON { "fields": [ "name", "email", "callPos.peer", "callPos[1].grouped" ], "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF" }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654" }, { "uuid": "76543210-68FF-18-3210-FEDCBA987654" } ] }

Pokud není v adresáři žádné pole se zadaným 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, jeho zadaná pole (v příkladu název, e-mail, telefonní čísla všech volajících stanic a pro druhou volající stanici i skupina) budou vrácena. To samé platí pro druhý uuid 76543210-68FF-18CA-3210-FEDCBA987654.


Identifikátor uuid 76543210-68FF-18-3210-FEDCBA987654 má nesprávný formát.


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
Název klíčeTypické vrácené hodnotyPopis

uuid

uuid

Unikátní uživatelský identifikátor (Unique User Identifier) nalezeného záznamu.

Various keys

různé

Zadaná pole záznamu v adresáři, která jsou vrácena. Viz api/dir/template.

timestamp

celé číslo;

Časová značka změn naposledy provedených pro každý vrácený záznam 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 záznam v adresáři vrácen.

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. V odpovědi se mohou vrátit následující chybové kódy:

  • EDIR_UUID_DOES_NOT_EXIST - záznam se zadaným identifikátorem uuid neexistuje (tj. nedá se aktualizovat).

  • 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 jako prázdný uuid.

Příklad odpovědi

{ "success": true, "result": { "series": "6423407687606431951", "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@abcd.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 39 }, { "uuid": "76543210-68FF-18CA-3210-FEDCBA987654", "errors": [ { "code": "EDIR_UUID_DOES_NOT_EXIST" } ] }, { "uuid": "76543210-68FF-18-3210-FEDCBA987654", "errors": [ { "code": "EDIR_UUID_INVALID_FORMAT" } ] } ] } }


První záznam v adresáři je úspěšně vrácen, jeho uuid a timestamp jsou vráceny.


Druhý záznam neexistuje (neexistuje záznam s daným uuid).


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