APIs und Automatisierung

Webhooks in falscher Reihenfolge: So verhindern Sie, dass ein altes Ereignis den Dateistatus zurücksetzt

Der Empfangszeitpunkt beweist nicht, welche Änderung zuerst erfolgt ist. Erfahren Sie, wie Sie den Webhook-Vertrag prüfen und den Dateistatus anhand überprüfbarer Kriterien abgleichen.

Apification
Diagramm von Datei-Ereignissen, die in unterschiedlicher Reihenfolge eintreffen, und einer Anwendung, die ihren Status abgleicht

Der Empfang belegt nicht die Reihenfolge der Änderungen

Ein Webhook kann Ihre Anwendung über ein asynchrones Ereignis informieren. Der Zeitpunkt, zu dem Ihr Server ihn empfängt, beweist jedoch weder, wann die Änderung erfolgt ist, noch, welche von zwei Änderungen zuerst stattfand. Überschreibt jede Benachrichtigung einfach den lokalen Datensatz, kann Ihre Ansicht deshalb veraltet sein.

Allgemeine Referenzen helfen, den Einsatz von Webhooks zu verstehen, legen aber keinen Ordnungsvertrag für Ihre Integration fest: Stripe stellt Webhooks als Möglichkeit vor, auf asynchrone Ereignisse zu reagieren ([Stripe-Dokumentation](https://docs.stripe.com/webhooks?locale=es-ES)); Microsoft empfiehlt Webhooks von Microsoft Graph, um auf Dateiänderungen in SharePoint Embedded zu reagieren ([Microsoft Learn](https://learn.microsoft.com/es-es/sharepoint/dev/embedded/build/respond-to-changes-webhooks)); und Shopify beschreibt ihre Verwendung zum Abrufen und Speichern von Ereignisdaten ([Shopify](https://help.shopify.com/es/manual/fulfillment/setup/notifications/webhooks)). Wie Sie Ereignisse ordnen oder abgleichen, sollten Sie der technischen Dokumentation des jeweiligen Anbieters entnehmen.

Die Implementierungsmuster in diesem Artikel sind allgemeine Empfehlungen und keine Zusicherungen zu Zustellung, Reihenfolge oder Konsistenz einer Plattform. Unterscheiden Sie den Zeitpunkt der Änderung, den Zeitpunkt der Ereignisausgabe und den Empfangszeitpunkt. Verwenden Sie Felder nur dann zum Vergleichen von Ereignissen, wenn der Anbieter ihre Semantik und ihren Geltungsbereich dokumentiert.

  • Halten Sie fest, was jedes Zeitfeld bedeutet und in welchem Geltungsbereich es vergleichbar ist.
  • Verwenden Sie die lokale Empfangszeit für die Beobachtbarkeit, nicht als Kausalitätsnachweis.
Der Empfang belegt nicht die Reihenfolge der Änderungen

Modellieren Sie den Fall einer falschen Reihenfolge

Nehmen wir an, „budget.docx“ wird in „budget-final.docx“ umbenannt und anschließend in einen Freigabeordner verschoben. Trifft die Benachrichtigung über das Verschieben zuerst und die über die Umbenennung später ein, kann das Anwenden jeder Nachricht als endgültige Wahrheit einen veralteten Speicherort oder Namen wiederherstellen. Eine später zugestellte Benachrichtigung macht das Ereignis nicht zur neuesten Änderung.

Skizzieren Sie vor der Implementierung den Ausgangszustand, die tatsächlichen Änderungen, die ausgegebenen Benachrichtigungen, die Empfangsreihenfolge und das erwartete lokale Ergebnis. Halten Sie fest, ob jede Benachrichtigung eine Teiländerung beschreibt oder einen vollständigen Status enthält. Dieser Unterschied beeinflusst, wie sie verarbeitet werden sollte.

  • Testen Sie den Fall, in dem Änderung A vor B erfolgt, ihre Benachrichtigung aber erst danach verarbeitet wird.
  • Prüfen Sie, dass der lokale Datensatz durch die Empfangsreihenfolge nicht auf einen früheren Stand zurückfällt.
Modellieren Sie den Fall einer falschen Reihenfolge

Prüfen Sie den Vertrag, bevor Sie Ereignisse vergleichen

Suchen Sie in der Dokumentation nach einem Sequenz-, Versions- oder Zeitfeld, das der Anbieter ausdrücklich als vergleichbar definiert. Prüfen Sie seine Bedeutung, seinen Geltungsbereich, den Umgang mit fehlenden Werten und ob der Wert zurückgesetzt werden kann. Ein Name wie „updated_at“ oder „version“ reicht allein nicht aus, um festzustellen, ob zwei Benachrichtigungen geordnet werden können.

Dokumentiert der Anbieter eine aufsteigende Sequenz, die für die betreffende Datei gilt, können Sie sie als Annahmekriterium verwenden: Speichern Sie den zuletzt akzeptierten Wert zusammen mit dem lokalen Status und vergleichen Sie jede Benachrichtigung gemäß den dokumentierten Regeln. Schützen Sie Vergleich und Schreibvorgang durch eine atomare Operation. Legen Sie fest, wie Sie mit gleichen, fehlenden oder ungültigen Werten umgehen, statt sie standardmäßig als aktuell zu behandeln.

  • Dokumentieren Sie das Feld, seine Semantik, den Vergleichsbereich und den Umgang mit nicht vergleichbaren Werten.
  • Eine atomare Aktualisierung schützt den lokalen Datensatz vor konkurrierenden Schreibvorgängen, beweist aber nicht, dass alle Ereignisse empfangen wurden.

Gibt es kein verlässliches Ordnungskriterium, ziehen Sie einen Abgleich durch erneutes Lesen in Betracht

Wenn kein dokumentiertes Ordnungsfeld vorhanden ist, besteht ein mögliches Entwurfsmuster darin, den Webhook als Hinweis darauf zu behandeln, dass sich die Datei möglicherweise geändert hat, und die Ressource über die API abzufragen, sofern der Anbieter diese Operation anbietet. Vergewissern Sie sich, dass Sie die Datei identifizieren können und die Antwort die benötigten Felder enthält.

Eine API-Antwort garantiert für sich allein nicht, dass Sie den neuesten Status aus der Ferne abrufen: Die Dokumentation des Anbieters sollte die Konsistenzgarantien und gegebenenfalls die Auswirkungen von Caches erläutern. Sind solche Garantien nicht dokumentiert, behandeln Sie das erneute Lesen als nützliche Informationsquelle, nicht als Aktualitätsnachweis.

Schlägt das erneute Lesen fehl oder lässt sich die Ressource damit nicht identifizieren, behalten Sie den vorhandenen lokalen Status bei und wenden Sie eine für Ihr System geeignete Wiederholungsrichtlinie an. Unterscheiden Sie einen vorübergehenden Fehler von der Bestätigung, dass die Datei nicht mehr existiert.

  • Prüfen Sie den Lesevorgang, die erforderliche Kennung, die zurückgegebenen Felder und die dokumentierten Konsistenzgarantien.
  • Machen Sie aus einem fehlgeschlagenen Lesevorgang weder eine Löschung noch eine bestätigte Aktualisierung.

Schützen Sie lokale Schreibvorgänge vor konkurrierenden Antworten

Zwei Benachrichtigungen können gleichzeitig Lesevorgänge auslösen. Dauert der erste länger und wird seine Antwort erst nach der zweiten gespeichert, könnte sie ein bereits gespeichertes Ergebnis ersetzen. Die Reihenfolge, in der Abfragen abgeschlossen werden, beweist nicht, welche Antwort neuere Daten aus der Ferne enthält.

Sie können Abgleiche pro Datei serialisieren oder jeder Anfrage eine lokale Generation zuweisen und diese beim Speichern prüfen. Diese Generation hilft zu verhindern, dass ein früherer lokaler Auftrag einen späteren überschreibt, legt aber nicht fest, welche Antwort neuere Daten aus der Ferne enthält. Dafür sind weiterhin die dokumentierten Garantien der API erforderlich. Eine andere Möglichkeit besteht darin, Benachrichtigungen zusammenzufassen und nach einer Ereignisflut eine Abfrage auszuführen, sofern die daraus entstehende Verzögerung akzeptabel ist.

  • Testen Sie API-Antworten, die in umgekehrter Reihenfolge zum Start der Abfragen eintreffen.
  • Unterscheiden Sie den Schutz vor veralteten lokalen Schreibvorgängen von der Aktualitätsgarantie für Daten aus der Ferne.

Testen Sie Wiederholungen, Permutationen und Fehler

Führen Sie dieselbe Gruppe von Änderungen mit Benachrichtigungen in normaler, umgekehrter und weiteren Reihenfolgen aus. Beziehen Sie wiederholte Benachrichtigungen ein: Deduplizierung ist ein verwandtes, aber vom Reihenfolgeproblem getrenntes Thema. Prüfen Sie den erwarteten Endstatus und nicht nur den Antwortcode des Empfängers.

Variieren Sie die Fälle: Umbenennen und Verschieben, Speicherort und Status ändern, zweimal umbenennen sowie Teilfelder aus Benachrichtigungen kombinieren. Ergänzen Sie Fehler beim Lesen über die API und zwei gleichzeitige Prozesse. Wenn Sie mit versionierten Dateien arbeiten, können Sie den lokalen Datensatz mit dem verfügbaren Verlauf vergleichen. Gehen Sie nicht davon aus, dass dieser Verlauf einen Ordnungsvertrag ersetzt.

  • Abnahmekriterium: Die getesteten Permutationen lassen den Datensatz im Vergleich zu dem gemäß den verfügbaren Garantien verifizierten Status nicht zurückfallen.
  • Protokollieren Sie Zustellungs-, Lese- und lokale Aktualisierungsfehler getrennt.

Protokollieren Sie das Nötige, um Abweichungen zu diagnostizieren

Protokollieren Sie eine sichere Referenz auf die Datei, den Ereignistyp, vorhandene dokumentierte Ordnungsfelder, den Empfangszeitpunkt, das Ergebnis des API-Lesevorgangs und die Entscheidung über den lokalen Schreibvorgang. Eine eigene Korrelationskennung kann dabei helfen, die Benachrichtigung bis zum Abgleich nachzuverfolgen. Speichern Sie keine Tokens, Geheimnisse oder vollständigen Datei-Inhalte und beschränken Sie personenbezogene Daten auf das Notwendige.

Halten Sie das Protokoll so aussagekräftig, dass sich feststellen lässt, ob das Ereignis empfangen wurde, ob die Ressource abgefragt werden konnte und warum ein Schreibvorgang akzeptiert oder abgelehnt wurde. Apification bietet die Integration über REST API und Webhooks; zu den Automatisierungsfunktionen gehören Wiederholungen, Verlauf und Statistiken. Prüfen Sie in der einschlägigen Dokumentation, welche Informationen in Ihrem Ablauf verfügbar sind. Diese Funktionen helfen bei der Überwachung einer Integration, legen aber kein Ordnungskriterium fest.

  • Wenn Empfang, Lesen, Vergleich und Schreiben getrennt protokolliert werden, lässt sich die Stelle der Abweichung leichter finden.
  • Nehmen Sie keine Zugangsdaten oder Geheimnisse in Protokolle auf.

Häufige Fragen

Kann ich Ereignisse nach dem Zeitpunkt ordnen, zu dem mein Server sie empfängt?

Nicht als Beweis dafür, welche Änderung zuerst erfolgt ist. Der Empfang kann sich verzögern. Verwenden Sie ein Ordnungsfeld nur, wenn der Anbieter seine Bedeutung und seinen Geltungsbereich dokumentiert.

Liefert ein API-Lesevorgang immer den neuesten Status?

Nicht unbedingt. Prüfen Sie in der Dokumentation die Konsistenzgarantien und mögliche Auswirkungen von Caches. Ohne diese Informationen sollten Sie eine Antwort nicht als Aktualitätsnachweis behandeln.

Was soll ich tun, wenn der Webhook kein Sequenzfeld enthält?

Bietet die API einen geeigneten Lesevorgang und ist dokumentiert, wie sich die Ressource identifizieren lässt, können Sie den Webhook als Hinweis für einen Abgleich behandeln. Prüfen Sie auch die Garantien des Lesevorgangs. Gibt es keine geeignete Option, konsultieren Sie den Vertrag des Anbieters.

Garantiert Apification, dass Datei-Webhooks in der richtigen Reihenfolge eintreffen?

Die verfügbaren Produktinformationen bestätigen die Integration über REST API und Webhooks sowie Wiederholungen, Verlauf und Statistiken für Automatisierungen. Eine Garantie zur Reihenfolge von Datei-Ereignissen wird darin nicht genannt. Prüfen Sie die einschlägige Dokumentation, bevor Sie sich darauf verlassen.

Quellen und weitere Informationen

Für diesen Artikel herangezogene Dokumentation.

Apification entdecken

Ähnliche Artikel

Zurück zum Blog