5.14.6 api dir query

Funkce /api/dir/query slouží k vyhledávání pole záznamů v adresáři podle iterátoru časových značek 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

series

Ne

řetězec

aktuální série zařízení

Řetězec představuje počet sérií časových značek v zařízení. Není-li klíč zadán, je uvažována současná série zařízení. Jestliže se zadaná série liší od současné série zařízení, zařízení vrátí svou sérii, nejvyšší hodnotu časové značky a neplatnou časovou značku.

fields

Ne

pole řetězců

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

V odpovědi musejí být specifikovány názvy 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.

iterator

Ne

objekt JSON

{"timestamp": 0}

Klíč definuje iterátor dotazu (iterátor časové značky je podporován). Iterátor časové značky je celočíselná časová značka, která indikuje, že se má vrátit první záznam v adresáři (pomocí funkcí api/dir/create, api/dir/update nebo api/dir/delete se vždy vrací poslední časová značka). Je-li hodnota iterátoru časové značky nulová, vrátí se všechny záznamy v adresáři. Je-li vyšší než aktuální hodnota časové značky v zařízení, zařízení vrátí svou sérii, nejvyšší hodnotu časové značky.


Příklad požadavku

URL: https://192.168.1.1/api/dir/query JSON { "series": "2229480630597592840", "fields": [ "name", "email", "callPos.peer", "callPos[1].grouped" ], "iterator": { "timestamp": 6 } }


Nesouhlasí-li klíč series s aktuálním klíčem series v zařízení, zařízení vrátí svou sérii, nejvyšší hodnotu časové značky a neplatnou časovou značku.


Je-li zadaná časová značka nižší než aktuální nejvyšší časová značka, vrátí se všechny vyšší časové značky.


Zařízení je schopno zvládnout až 10000 unikátních uživatelských identifikátorů. Když se tento počet zvýší, zařízení vrátí klíč invalid, který znamená, že adresář má neznámou historii (některé záznamy byly vymazány a nejsou již uloženy v zařízení).


Je-li zadaná časová značka nižší než neplatná časová značka, zařízení vrátí svou aktuální sérii, nejvyšší hodnotu časové značky a neplatnou časovou značku.


Odpověď

Odpověď je ve formátu application/json. Objekt result obsahuje klíče series a users.


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. Časová značka je uvedena, jen když je záznam v adresáři vrácen.


Příklad odpovědi

{ "success": true, "result": { "series": "2229480630597592840", "users": [ { "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", "name": "ABCD", "email": "abcd@abcd.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 7 }, { "uuid": "A6543210-68FF-18CA-3210-FEDCBA987654", "name": "DEFG", "email": "defgd@defg.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 9 }, { "uuid": "044197A7-54AD-7577-6EEA-787A6097263E", "name": "HIJK", "email": "hijk@hijk.cz", "callPos": [ { "peer": "" }, { "peer": "", "grouped": "false" }, { "peer": "" } ], "timestamp": 10 } ] } }}


Vrátí se tři záznamy v adresáři, které mají časovou značku vyšší než 6 (v tomto případě je maximální časová značka v adresáři 10).