Architektur
Bitrix24-Integrationen: Warteschlangen, Wiederholungen und Schutz vor Duplikaten
Was beim Datenaustausch zu beachten ist, wenn eine externe Anfrage wegen Zeitüberschreitung endet, die Antwort verloren geht oder ein Ereignis mehrfach eintrifft.
Ein Timeout bedeutet, dass innerhalb der vorgesehenen Zeit keine Antwort eingetroffen ist. Er beweist nicht, dass die externe Operation fehlgeschlagen ist. Der Dienst könnte die Daten gespeichert haben, während die Antwort unterwegs verloren ging. Wird das Objekt einfach noch einmal angelegt, entsteht dann ein Duplikat. Zuverlässiger Datenaustausch braucht deshalb Regeln zum Erkennen und Wiederherstellen von Operationen; endlose Wiederholungsschleifen reichen nicht aus.
Hier folgt ein Architekturansatz für Integrationen von Unternehmenssystemen. Er beschreibt keine eingebaute Garantie von Bitrix24: Die konkrete Umsetzung hängt von den APIs beider Seiten ab.
Zuerst die Datenverantwortung bestimmen
Legen Sie für jede Entität fest, welches System maßgeblich ist und welche Felder die andere Seite ändern darf. Ohne diese Regel können zwei Automatisierungen beim bidirektionalen Austausch gegenseitig ihre Daten überschreiben.
Eine Zuordnung der Kennungen ist hilfreich: Quelle, externe ID und lokale ID. Zusätzlich braucht die Operation einen stabilen Schlüssel, der bei erneuter Zustellung gleich bleibt. Ein neuer Zufallsschlüssel pro Versuch hilft nicht, Wiederholungen zu erkennen.
Was Idempotenz bedeutet
Eine idempotente Verarbeitung erzeugt beim Wiederholen derselben Operation keinen zusätzlichen unerwünschten Effekt. Ein erneut zugestelltes Registrierungsereignis einer Anfrage sollte beispielsweise auf die bereits angelegte Aufgabe verweisen, statt eine weitere anzulegen.
Die Prüfung „Datensatz existiert noch nicht“ vor dem Anlegen reicht bei paralleler Verarbeitung nicht aus. Zwei Verarbeitungsprozesse, hier Handler genannt, können gleichzeitig feststellen, dass der Datensatz fehlt. Deshalb braucht der Speicher einen geeigneten Schutz, oder die empfangende API muss einen Idempotenzmechanismus bereitstellen.
Wenn das externe System keinen Operationsschlüssel unterstützt, brauchen Sie einen anderen Abgleich. Je nach API können Sie nach einer vereinbarten externen Kennung suchen. Lässt sich das Ergebnis nicht eindeutig feststellen, kann eine manuelle Klärung nötig sein. Eine Zustellung „genau einmal“ zwischen beliebigen Systemen lässt sich nicht versprechen.
Wozu eine Warteschlange dient
Eine Warteschlange trennt Nutzeraktion und Austauschversuch und speichert dessen Zustand. Sie muss einen Prozessneustart überstehen und sichtbar machen, was noch unerledigt ist.
Beispielfelder sind Operations-ID, Ereignistyp, Entitätsreferenz, Datenversion, Zustand, Versuchszahl, nächster Versuch und letzter Fehlercode. Der Datenumfang hängt von den Wiederherstellungsanforderungen ab; Zugangsdaten und überflüssige personenbezogene Daten gehören nicht hinein.
| Zustand | Bedeutung |
|---|---|
| Wartend | Operation zur Verarbeitung angenommen |
| In Bearbeitung | Ein bestimmter Handler hat den Versuch übernommen |
| Wiederholung erforderlich | Vorübergehender Fehler bestätigt |
| Abgeschlossen | Erwartetes Ergebnis empfangen und gespeichert |
| Klärung erforderlich | Automatische Wiederholung unsicher oder ausgeschöpft |
Wenn ein Handler einen Eintrag übernimmt, darf kein zweiter Handler ihn gleichzeitig verarbeiten. Legen Sie auch fest, wie ein Auftrag nach einem Absturz wiederhergestellt wird. Ein anderer Handler darf ihn nur dann sicher übernehmen, wenn wiederholte Nebenwirkungen verhindert werden.
Fehlertypen unterscheiden
Ist der Dienst vorübergehend nicht erreichbar, kann ein weiterer Versuch mit wachsender Verzögerung und einem kleinen Zufallsanteil geplant werden. So sinkt das Risiko, dass alle Handler gleichzeitig erneut auf den Dienst zugreifen.
Bei ungültigem Datenformat, fehlenden Rechten oder fachlichen Konflikten muss die Ursache behoben werden. Dieselbe Anfrage unverändert zu wiederholen hilft hier nicht. Tritt nach dem Senden ein Timeout auf, bleibt möglicherweise offen, ob die Operation fehlgeschlagen ist oder nur ihre Antwort verloren ging.
Berücksichtigen Sie bei Bitrix24 REST die dokumentierten Fehler und Limits. Cloud-Grenzen lassen sich nicht automatisch auf On-Premise übertragen: Dort sind Server- und Moduleinstellungen wesentlich. Gleichen Sie Zahlenwerte mit der aktuellen Dokumentation und der konkreten Umgebung ab.
Konsistenz und Ereignisreihenfolge
Sind die Daten gespeichert, aber der Warteschlangeneintrag verloren, beginnt kein Austausch. Liegen beide Einträge in derselben transaktionalen Datenbank, können Auftrag und Datenänderung gemeinsam in einer Transaktion gespeichert werden: der Outbox-Ansatz. Unterschiedliche Speicher erfordern eine eigene Wiederherstellungs- und Abgleichstrategie.
Ein weiterer Punkt sind verspätete Ereignisse. Eine ältere Änderung darf eine neuere nicht allein wegen späterer Zustellung überschreiben. Dafür dient eine abgestimmte Entitätsversion oder eine andere von beiden Seiten unterstützte Reihenfolge.
Mindestumfang der Prüfung
- Dieselbe Operation zweimal zustellen: Es entsteht kein unerwünschtes Duplikat.
- Zwei Handler starten: Sie bearbeiten denselben Eintrag nicht gleichzeitig.
- Die Antwort nach externer Speicherung unterbrechen: Eine Wiederholung erzeugt kein zweites Objekt.
- Den Handler neu starten: Unfertige Aufträge werden erkannt und wiederhergestellt.
- Eine alte Änderung nach einer neuen zustellen: Der aktuelle Zustand bleibt erhalten.
- Ungültige Daten übergeben: Der Auftrag erhält einen verständlichen Fehler und läuft nicht endlos weiter.
Ergänzen Sie diese Prüfungen durch Betriebsdaten: das Alter des ältesten Auftrags, die Fehleranzahl, die Zustände der Warteschlange und Logeinträge, die sich einer Operation zuordnen lassen. Ein laufender Handler allein belegt noch keinen funktionierenden Austausch.