Skip to main content
Web Hooks

Ako sa dozvedieť o zmene v systéme ABRA Flexi

Lenka Haringerová avatar
Written by Lenka Haringerová
Updated over a year ago

Web Hooks predstavujú spôsob, ako sa dozvedieť o zmenách v systéme ABRA Flexi vo vašej aplikácii v reálnom čase. Princíp je jednoduchý: keď v databáze ABRA Flexi dôjde k zmene, odošle sa požiadavka POST HTTP (zvyčajne v priebehu niekoľkých sekúnd) na všetky zaregistrované adresy URL. Obsahom požiadavky je výpis zmien naraz od posledného volania hooku v rovnakom formáte, aký získate z ABRA Flexi prostredníctvom rozhrania Changes API.

Postup

Rozhranie Changes API musí byť povolené. Hooky musia byť povolené aj v konfiguračnom súbore ABRA Flexi Server flexibee-server.xml(umiestnenie adresárov flexibee-server.xml):

...<entry key="enableHooks">true</entry>....

Dôvodom je, že pri spustení servera je potrebné okamžite spustiť jadro (pozri tiež automatický štart jadra), čo je časovo náročná operácia. Poznámka: ak máte nastavenú hodnotu enableHooks na true, nie je potrebné nastavovať startKernel.

Web Hook sa zaregistruje pomocou požiadavky PUT (alebo POST) na adresu /c/{firm}/hooks s nasledujúcimi parametrami:

povinné

?url=http://muj.server.cz/hook.php

URL, ktorá sa má zavolať

?format=XML

Formát údajov (možné hodnoty sú XML a JSON)

voliteľné

?lastVersion=123

Verzia, od ktorej sa začnú posielať ďalšie zmeny, t. j. nasledujúca vyššia verzia. Predvolená hodnota sa rovná aktuálnej globálnej verzii(globalVersion) v okamihu registrácie hooku. Prípustné hodnoty sú z intervalu: [0, globalVersion].

?secKey=MyHookSecretToken0687

Ľubovoľný reťazec, ktorý sa má odoslať s každým oznámením o zmene hlavičky HTTP. Slúži na jednoduché overenie, či prichádzajúce oznámenie patrí vášmu zaregistrovanému háku. Názov kľúča v hlavičke HTTP je X-FB-Hook-SecKey.

?skipUrlTest=true

Potlačenie testu funkčnosti odovzdanej adresy URL.

Napríklad:

curl -u user:password -L -k -X PUT "https://localhost:5434/c/{firma}/hooks.xml?url=http://muj.server.cz/hook.php&format=XML&lastVersion=123&secKey=MyHookSecretToken0687"

Registrácia vykoná test odovzdanej adresy URL odoslaním prázdneho oznámenia. Ak je návratový kód iný ako 2xx, hook nebude zaregistrovaný. Vykonanie testu možno prepísať pomocou parametra skipUrlTest.

ABRA Flexi podporuje SNI od verzie 2017.1.1. To znamená, že je možné zaregistrovať hooky smerujúce na virtuálneho hostiteľa HTTPS.

Zatiaľ nie je možné určiť, na ktoré registrácie sa má hook odkazovať, vždy je upozornený na všetky zmeny, ktoré nastanú v systéme ABRA Flexi.

Úspech je ako zvyčajne oznámený stavovým kódom 200 a neúspech kódom 400 (odpoveď obsahuje textový popis príčiny).

Zoznam registrovaných hookov sa nachádza na adrese /c/{firma}/hooks, neregistrované hooky možno vyžiadať DELETE na adrese /c/{firma}/hooks/{id}.

Správanie web hooks pri chybe

Ak dôjde k chybe pri spracovaní hooks, server sa pokúsi opätovne odoslať požiadavky. Ak hook naďalej zlyháva, volania sa začnú oneskorovať. Ak je služba úplne nedostupná, každý hovor sa zvyčajne začne neskôr. Na tento účel sa používa pokuta, ktorá predstavuje čas medzi pokusmi.

Aktuálnu pokutu môžete získať pomocou funkcie GET:

curl -u user:password -L -k "https://localhost:5434/c/{firma}/hooks/{id}.xml"

Obnovenie trestu a okamžité volanie hookov zabezpečí požiadavku PUT:

curl -u user:password -L -k -X PUT "https://localhost:5434/c/{firma}/hooks/{id}/retry"

Zaregistrované hooky sú uložené v databáze, takže hook bude odoslaný aj po reštarte servera. Služba zaručuje, že sa nestratia žiadne zmeny a všetky sa odovzdajú zaregistrovanému háku.

Odporúčania pre implementáciu hákov

Celý mechanizmus funguje na princípe maximálneho úsilia. To znamená, že aj keď sa snažíme doručiť oznámenia čo najskôr a vyhnúť sa duplicitám, musíme počítať s tým, že môže dôjsť k oneskoreniu alebo duplicite (jednoducho doručíme tú istú požiadavku viackrát). Ak chcete odstrániť duplicitu, môžete spracovať globálnu verziu.

Spracovanie hooka by malo trvať čo najmenej času (< 15 sekúnd) a rozhodne nesmie presiahnuť 30 sekúnd, inak sa volanie považuje za neúspešné. Odpoveď musí mať stavový kód 200 (alebo 2xx) a nemala by obsahovať žiadne telo. Ak je niektorá z týchto podmienok porušená, hook je penalizovaný (t. j. určitý čas sa vôbec nevyvolá) a v krajnom prípade sa môže úplne vypnúť.

Ideálna implementácia hooka vykonáva len perzistenciu prijatých zmien s možným rýchlym filtrovaním relevantných zmien a vynechaním duplicít (už spracovaných zmien). Skutočné spracovanie prijatých zmien by malo prebiehať asynchrónne v nezávislom vlákne.

Ďalšie podporované stavové kódy odpovedí

Okrem klasického potvrdenia stavu 200 podporuje spracovanie hookov v odpovediach nasledujúce možnosti:

301 (Moved Permanently) / 308 (Trvalé presmerovanie)V prípade, že presmerovanie vedie na platnú adresu URL, registrovaná adresa hooka sa aktualizuje a po krátkom treste sa zmeny oznámia na novo registrovanú adresu.410 (Gone)Predpokladá sa, že hook bol trvalo zrušený a na strane ABRA Flexi je automaticky odregistrovaný.

Did this answer your question?