.. _api_changes: ================================ Změny a tvorba entit ================================ API poskytuje sadu funkcí, které umožňují do systému přidávat nové entity, aktualizovat stávající a obohacovat je o další informace. Rozhraní je koncipováno tak, že požadavky na změny či vytvoření záznamu entity se do systému nahrávají ve formě dávek. Dávka může obsahovat jednu nebo více změn. V REST rozhraní je k dispozici metoda pro vložení nové dávky. Současně jsou k dispozici metody pro zjištění stavu zpracování dávky. V rámci dávkových operací je možné: - :ref:`vložit nový záznam entity ` - :ref:`vložit část záznamu entity `, například: jméno, další identifikátor - :ref:`přidat prvky popisu do části záznamu ` - :ref:`aktualizovat hodnoty prvků popisu ` - :ref:`vymazat část záznamu entity nebo jeho prvky popisu ` - :ref:`změnit stav záznamu ` - :ref:`změnit preferované jméno ` - :ref:`změnit třídu/podtřídu entity ` .. _api_changes_batch: --------------------- Princip dávkového API --------------------- Dávkové API umožňuje vložení aktualizační dávky pro provedení změn. Každá dávka je identifikována svým UUID, které je její součástí. Pomocí tohoto UUID je možné zjistit stav zpracování dávky. Pokud byla dávka úspěšně zpracována tak, není možné shodné UUID opakovaně použít pro jinou dávku. Dávka je vždy zpracována jako celek nebo jako celek odmítnuta. Jednotlivé operace v rámci dávky pracují s právě jedním záznamem entity. Součástí zápisu operace je identifikátor měněné entity a současně lokální identifikátor entity platný v rámci dávky. Pokud se pracuje s již existujícím záznamem, tak se uvádí jeho identifikátor a identifikátor poslední verze tohoto záznamu entity. Úprava stávajícího záznamu entity je možná jen v případě shody identifikátoru poslední verze s aktuálně platnou verzí. Výsledkem úspěšné dávkové operace je provedení transakce v databázi. Identifikátor proběhlé transakce se vrací jako součást odpovědi. Součástí úspěšné odpovědi jsou identifikátory nově zapsaných entit, pro každý změněný záznam se vrací identifikátor jeho verze po provedení změny. V případě, kdy se u záznamu entity v rámci jedné dávky provádí více změn, tak se u prvního výskytu uvede jeho identifikátor, číslo revize a jeho relativní ID. Pro další odkazy se použije relativní ID. Příklad použití relativního ID je v části :ref:`api_changes_del`. .. _api_changes_add_ap: ------------------------- Vložení entity ------------------------- Záznam entity se vkládá pomocí struktury :token:`CreateEntity` dle :ref:`XSD schématu `. Příklad založení entity ---------------------------------- .. literalinclude:: schema/priklad1.xml :language: xml Odpověď na založení: .. literalinclude:: schema/priklad1resp.xml :language: xml .. _api_changes_add_part: -------------------- Vložení části popisu -------------------- Částí popisu entity se rozumí označení, další identifikátor, vztah apod. Část popisu se vkládá pomocí struktury :token:`Part`. Příklad vložení části --------------------- .. literalinclude:: schema/priklad2.xml :language: xml .. _api_changes_add_items: -------------------- Přidání prvků popisu -------------------- Pomocí struktury :token:`NewItems` je možné přidat prvky popisu do dané části záznamu entity. Příklad vložení prvků popisu ---------------------------- .. literalinclude:: schema/priklad3.xml :language: xml .. _api_changes_upd_items: ------------------------------- Aktualizace hodnot prvků popisu ------------------------------- Pomocí struktury :token:`UpdateItems` je možné aktualizovat hodnoty prvků popisu. Aktualizovat je možné hodnoty jen u existujících prvků popisu. Pomocí aktualizace hodnot je možné také k prvku popisu přidat jeho UUID. Pro změnu hodnot opakovatelných prvků popisu musí být vždy nastaveno jejich UUID. Pokud je prvku popisu přiděleno UUID, tak toto UUID je pevné a dále neměnné. Příklad aktualizace prvků popisu -------------------------------- .. literalinclude:: schema/priklad4.xml :language: xml .. _api_changes_del: -------------------------------- Vymazání části záznamu entity -------------------------------- Vymazat je možné část záznamu entity nebo jeho vybrané prvky popisu. Příklad vymazání části ---------------------- .. literalinclude:: schema/priklad5.xml :language: xml .. _api_changes_setstate: ----------------------------- Změna stavu záznamu entity ----------------------------- U záznamu entity je možné změnit její stav. Stavy entity jsou popsané v části :ref:`ont_states`. Přechod mezi stavy je možný v závislosti na nastavení :ref:`oprávnění uživatele `. Příklad změny stavu ------------------- .. literalinclude:: schema/priklad6.xml :language: xml .. _api_changes_setprefname: ------------------------- Změna preferovaného jména ------------------------- Příklad změny preferovaného jména --------------------------------- .. literalinclude:: schema/priklad7.xml :language: xml .. _api_changes_setaptype: -------------------- Změna třídy/podtřídy -------------------- Příklad změny podtřídy entity ---------------------------------------- .. literalinclude:: schema/priklad8.xml :language: xml