Web-Haken
Web Hooks sind eine Möglichkeit, sich in Echtzeit über Änderungen in ABRA Flexi in Ihrer Anwendung zu informieren. Das Prinzip ist einfach: Bei einer Änderung in der ABRA Flexi-Datenbank wird eine POST-HTTP-Anfrage (in der Regel innerhalb weniger Sekunden) an alle registrierten URLs gesendet. Der Inhalt der Anfrage ist eine Auflistung der Änderungen seit dem letzten Hook-Aufruf, und zwar in demselben Format, das Sie von ABRA Flexi über die Changes API erhalten.
Verfahren
Die Änderungs-API muss aktiviert sein. Außerdem müssen Hooks in der Konfigurationsdatei ABRA Flexi Server flexibee-server.xml aktiviert werden(Speicherort der Verzeichnisse flexibee-server.xml):
...<entry key="enableHooks">true</entry>....
Der Grund dafür ist, dass beim Start des Servers der Kernel sofort gestartet werden muss (siehe auch automatischer Kernel-Start), was eine zeitaufwändige Operation ist. Hinweis: Wenn Sie enableHooks auf true gesetzt haben, ist es nicht notwendig, startKernel zu setzen.
Der Haken wird mit einer PUT- (oder POST-) Anfrage an /c/{firmen-ID}/hooks mit den folgenden Parametern registriert:
obligatorisch |
|
| Aufzurufende URL |
| Datenformat (mögliche Werte sind |
optional |
|
| Die Version, ab der die nächsten Änderungen gesendet werden, d. h. die nächsthöhere Version. Der Standardwert ist gleich der aktuellen globalen Version |
| Eine beliebige Zeichenkette, die mit jeder HTTP-Header-Änderungsmeldung gesendet wird. Sie dient dazu, auf einfache Weise zu überprüfen, ob die eingehende Benachrichtigung zu Ihrem registrierten Haken gehört. Der Name des Schlüssels im HTTP-Header lautet |
| Unterdrücken Sie den Funktionstest der übergebenen URL. |
Zum Beispiel:
curl -u user:password -L -k -X PUT "https://localhost:5434/c/{firmen-ID}/hooks.xml?url=http://muj.server.cz/hook.php&format=XML&lastVersion=123&secKey=MyHookSecretToken0687"
Bei der Registrierung wird ein Test der übergebenen URL durchgeführt, indem eine leere Benachrichtigung gesendet wird. Ist der Rückgabecode anders als 2xx, wird der Haken nicht registriert. Die Ausführung des Tests kann mit dem Parameter skipUrlTest außer Kraft gesetzt werden.
ABRA Flexi unterstützt SNI seit Version 2017.1.1. Dies bedeutet, dass es möglich ist, Haken zu registrieren, die auf einen virtuellen HTTPS-Host zeigen.
Derzeit ist es nicht möglich, festzulegen, auf welche Registrierungen sich der Haken beziehen soll, er wird immer über alle Änderungen in ABRA Flexi informiert.
Wie üblich wird ein Erfolg mit dem Statuscode 200 und ein Misserfolg mit dem Code 400 gemeldet (die Antwort enthält eine textliche Beschreibung der Ursache).
Eine Liste der registrierten Hooks befindet sich unter /c/{firmen-ID}/hooks, nicht registrierte Hooks können unter /c/{firmen-ID}/hooks/{id} DELETE angefordert werden.
Hook-Verhalten im Fehlerfall
Wenn ein Fehler bei der Verarbeitung von Hooks auftritt, versucht der Server, die Anfragen erneut zu senden. Wenn der Haken weiterhin ausfällt, beginnen sich die Hakenrufe zu verzögern. Wenn der Dienst nicht verfügbar ist, wird jeder Anruf in der Regel später gestartet. Zu diesem Zweck wird eine Strafe verwendet, um die Zeit zwischen den Versuchen darzustellen.
Sie können die aktuelle Strafe mit GET abrufen:
curl -u user:password -L -k "https://localhost:5434/c/{firmen-ID}/hooks/{id}.xml"Das Zurücksetzen der Strafe und der sofortige Aufruf von Hooks gewährleistet eine PUT-Anforderung:
curl -u user:password -L -k -X PUT "https://localhost:5434/c/{firmen-ID}/hooks/{id}/retry"Die registrierten Hooks werden in der Datenbank gespeichert, so dass der Hook auch nach einem Neustart des Servers gesendet wird. Der Dienst garantiert, dass keine Änderungen verloren gehen und alle an den registrierten Haken weitergeleitet werden.
Empfehlungen für die Umsetzung der Haken
Der gesamte Mechanismus funktioniert nach dem Prinzip des besten Bemühens. Das bedeutet, dass wir zwar versuchen, die Meldungen so schnell wie möglich zuzustellen und Doppelmeldungen zu vermeiden, aber wir müssen auch berücksichtigen, dass es zu Verzögerungen oder Doppelmeldungen kommen kann (einfach dieselbe Anfrage mehrmals zustellen). Um Doppelungen zu vermeiden, können Sie globalVersion behandeln.
Die Bearbeitung des Hooks sollte so wenig Zeit wie möglich in Anspruch nehmen (< 15 Sekunden) und darf auf keinen Fall länger als 30 Sekunden dauern, da der Aufruf sonst als Fehlschlag gewertet wird. Die Antwort muss einen Statuscode von 200 (oder 2xx) haben und sollte keinen Text enthalten. Wird eine dieser Bedingungen verletzt, wird der Hook bestraft (d.h. er wird für einige Zeit überhaupt nicht aufgerufen) und im Extremfall sogar ganz abgeschaltet.
Die ideale Hook-Implementierung führt nur die Persistenz der empfangenen Änderungen durch, wobei eine schnelle Filterung nach relevanten Änderungen möglich ist und Duplikate (bereits verarbeitete Änderungen) übersprungen werden. Die eigentliche Verarbeitung der empfangenen Änderungen sollte asynchron in einem unabhängigen Thread ablaufen.
Andere unterstützte Antwortstatuscodes
Zusätzlich zur klassischen 200-Status-Bestätigung unterstützt die Hook-Verarbeitung die folgenden Optionen in den Antworten:
301 (Moved Permanently) / 308 (Permanent Redirect)Falls die Weiterleitung zu einer gültigen URL führt, wird die registrierte Hook-Adresse aktualisiert und nach einer kurzen Strafe werden die Änderungen an die neu registrierte Adresse gemeldet. 410 (Gone) Es wird davon ausgegangen, dass der Haken endgültig gelöscht wurde, und auf der ABRA Flexi Seite wird er automatisch abgemeldet.