Webové háčiky
Webové háčiky 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 háčika v rovnakom formáte, aký získate z ABRA Flexi prostredníctvom rozhrania Changes API.
Postup
Rozhranie Changes API musí byť povolené. Háčiky 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.
Háčik sa zaregistruje pomocou požiadavky PUT (alebo POST) na adresu /c/{firm}/hooks s nasledujúcimi parametrami:
povinné | |
| URL, ktorá sa má zavolať |
| Formát údajov (možné hodnoty sú |
voliteľné | |
| 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 |
| Ľ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 |
| 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, háčik 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ť háčiky smerujúce na virtuálneho hostiteľa HTTPS.
Zatiaľ nie je možné určiť, na ktoré registrácie sa má háčik 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 háčikov sa nachádza na adrese /c/{firma}/hooks, neregistrované háčiky možno vyžiadať DELETE na adrese /c/{firma}/hooks/{id}.
Správanie háčika pri chybe
Ak dôjde k chybe pri spracovaní háčika, server sa pokúsi opätovne odoslať požiadavky. Ak háčik naďalej zlyháva, háčikové 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 háčikov zabezpečí požiadavku PUT:
curl -u user:password -L -k -X PUT "https://localhost:5434/c/{firma}/hooks/{id}/retry"Zaregistrované háčiky sú uložené v databáze, takže háčik 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 háčika 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á, háčik 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 háčika 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 háčikov v odpovediach nasledujúce možnosti:
301 (Moved Permanently) / 308 (Trvalé presmerovanie)V prípade, že presmerovanie vedie na platnú adresu URL, registrovaná adresa háčika sa aktualizuje a po krátkom treste sa zmeny oznámia na novo registrovanú adresu.410 (Gone)Predpokladá sa, že háčik bol trvalo zrušený a na strane ABRA Flexi je automaticky odregistrovaný.