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žadavky

Požadavek obsahuje parametr query a parametry ve formátu application/json.

parametr typ očekávané hodnoty výchozí hodnota popis

force

query

1 (True)

0 (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

application/json

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

n/a

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

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.

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).

Příklady požadavku

Požadavek 1: Vytvoření nového adresáře

URL: https://192.168.1.1/api/dir/create?force=1
JSON: 
{
  "users": [
    {
      "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF",
      "name": "Julius Thompson",
      "email": "Julius@snlsa.com",
      "access": {
        "pin": "1234"
      }
    },
    {
      "name": "Carlos Inpiers",
      "owner": "My2N",
      "email": "Carlos_Inpieros@emailos.cz"
    },
    {
      "uuid": "01234567-89AB-CDEF-0123-456789ABCDEF",
      "name": "Fridrich Dairy",
      "email": "mycountry",
      "access": {
        "pin": "5678"
      },
      "test": "something",
      "albert": "einstein"
    },
    {},
    {}
  ]
}

První záznam: 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).
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.

Požadavek 2: Vytvoření 3 nových uživatelů

URL: https://192.168.1.1/api/dir/create
JSON:
{
   "users":[
      {
         "name":"user1",
         "email":"user1gmail.com",
         "callPos":[
            {
               "peer":"2246",
               "profiles":"",
               "grouped":false
            }
         ]
      },
      {
         "name":"user2",
         "email":"user2@gmail.com",
         "callPos":[
            {
               "peer":"2246",
               "profiles":"",
               "grouped":false
            }
         ]
      },
      {
         "name":"user3",
         "email":"user3@gmail.com",
         "callPos":[
            {
               "peer":"234324234",
               "profiles":"",
               "grouped":false
            }
         ]
      }
   ]
}

Požadavek se snaží vytvořit tři nové záznamy v adresáři. Jednotlivým záznamům se snaží přiřadit náhodný identifikátor uuid, nastavit jejich jméno, e-mail a informace o volání (CallPos). Zbylým parametrům ponechá 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_DOES_NOT_EXIST` – uživatel s daným uuid neexistuje. `EDIR_UUID_IS_MISSING` – chybí povinný parameter 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_UUID_ALREADY_EXISTS` – v adresáři existuje záznam se zadaným identifikátorem uuid a klíč force je nastaven na 0 (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_NOT_AVAILABLE` – zadaný klíč není platný pro daný model zařízení. 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říklady odpovědí

Odpověď na požadavek 1: Vytvoření nového adresáře

{
  "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.

Odpověď na požadavek 2: Vytvoření 3 nových uživatelů

{
   "success":true,
   "result":{
      "series":"2068093780728692847",
      "users":[
         {
            "uuid":"01234567-89AB-CDEF-0123-456789ABCDCC",
            "errors":[
               {
                  "code":"EDIR_FIELD_VALUE_ERROR",
                  "field":"email"
               }
            ]
         },
         {
            "uuid":"01234567-89AB-CDEF-0123-456789ABCDCB",
            "timestamp":15207
         },
         {
            "uuid":"01234567-89AB-CDEF-0123-456789ABCDCA",
            "timestamp":15208
         }
      ]
   }
}

E-mail záznamu pro uživatele user1 nebyl platný, záznam tedy nebyl vytvořen. Zbylí dva uživatelé byli vytvořeni úspěšně.