Asynchronous Processing nimmt den ganzen Stapel, im Tempo jedes Systems
Maesn setzt kein eigenes Rate-Limit. Die Systeme dahinter schon, in Einheiten, die nichts gemeinsam haben, also nimmt die Warteschlange Ihr Volumen auf und gibt es im Tempo frei, das jedes Ziel erlaubt, die Anfragen eines Mandanten der Reihe nach, und lange Vorgänge antworten sofort mit einer Task, der Sie folgen können.
Was ist Asynchronous Processing
Tausend Rechnungen zu senden ist kein Durchsatzproblem. Ihre Seite erzeugt sie in einer Sekunde, und das Netz trägt sie. Die Frage ist, ob das System am anderen Ende sie in diesem Tempo annimmt, und die Antwort ist fast immer nein, auf eine Weise, die für dieses System spezifisch ist und irgendwo steht, wo Sie noch nicht gelesen haben. Volumen ist in einer Anbindung eine Frage der Erlaubnis, nicht der Leistung.
Asynchronous Processing ist die Ebene, die das für Sie beantwortet, und der Mechanismus ist eine Warteschlange. Statt Ihre Anfrage direkt an das Zielsystem zu reichen, reiht Maesn sie ein und arbeitet diese Schlange in dem Tempo ab, das das Ziel annimmt. Nimmt ein System fünf Anfragen pro Sekunde, können Sie hundert übergeben: Sie verlassen die Schlange zu fünft, in Ihrer Sendereihenfolge, und keine kommt mit der Bitte zurück, langsamer zu machen.
Aus der Warteschlange folgen drei Dinge und nicht eines. Das Tempo ist das erste. Das zweite ist, dass manche Vorgänge sich nicht abschließen lassen, solange eine Verbindung offen ist, sie antworten also mit einer Kennung für die Arbeit statt mit dem Ergebnis, und Sie gehen ihr nach, wann es Ihnen passt. Das dritte kostet am meisten, wenn es schiefgeht: Anfragen, die eine Schlange einzeln verlassen, können beim Token-Refresh nicht kollidieren, und dieser Fehler endet damit, dass Ihr Kunde sich erneut anmeldet. Alle drei nehmen Ihrem Code dieselbe Annahme, dass eine Anfrage in dem Moment fertig ist, in dem Sie sie senden.
Bei einer Ebene in der Mitte würden Sie zu Recht ein weiteres Limit erwarten. Die Referenz zu Rate-Limits sagt es in einem Satz: Maesns Unified APIs setzen keine eigenen Rate-Limits um. Die Limits, auf die es ankommt, gehören den Zielsystemen, sie gelten für Maesns Mandanten, und die Arbeit liegt darin, sie abzufangen statt sie weiterzureichen.
Jedes System zählt etwas anderes
Ein Rate-Limit ist nie nur eine Zahl. Es ist eine Zahl, ein Fenster und das, worauf das Fenster sich bezieht, und keine zwei Systeme sind sich über alle drei einig.
Liest man diese Liste als Spezifikation, wird der Umfang der Aufgabe offensichtlich. Ein Limiter, der zwei Anfragen pro Sekunde achtet, hat die falsche Form für einen, der zweihundert pro Minute gegen drei Fenster gleichzeitig zählt, und beide haben die falsche Form für ein System, das eine Anfrage auf einmal annimmt, oder eines, das einem GET und einem POST verschiedene Beträge aus einem gemeinsamen Budget abzieht. Ob das Budget zu Ihrer Anwendung, zur Gesellschaft des Endkunden, zu einem Nutzer oder zu einem Mandanten gehört, entscheidet, ob der geschäftige Nachmittag eines Kunden einen anderen aushungern kann. Und wo der Wert nicht veröffentlicht ist, findet man ihn nur, indem man ihn in der Produktion überschreitet.
Ein Hebel kommt vor der Taktung und ist der günstigere von beiden: Die Anfrage, die Sie nie senden, kostet nichts. Jedes System nur nach dem zu fragen, was sich seit Ihrem letzten Abgleich geändert hat, über den Delta-Filter auf fast jedem Endpunkt, hält die meisten Abgleichläufe bequem unter Limits, die ein vollständiges Neulesen jede Nacht reißen würde. Die Taktung trägt das Volumen, das Sie wirklich senden müssen.
Ein Schwall rein, ein Tempo, das jedes System annimmt
Feuern Sie Hunderte oder Tausende Anfragen auf Maesn ab, werden sie angenommen, gehalten und in einem Tempo an das Zielsystem abgegeben, das es erlaubt. In Ihrem Code ändert sich nichts zwischen einem System, das zwei Aufrufe pro Sekunde erlaubt, und einem, das tausend Credits pro Minute verbraucht, wobei ein GET eins und ein POST drei kostet, und nichts in Ihrem Code muss wissen, welches welches ist. Ein wöchentlicher Stapel von Zehntausenden Rechnungen ist der gewöhnliche Fall, nicht der Sonderfall. Die Arbeit kommt an, ohne dass Sie steuern, wann.
Die Reihenfolge wiegt schwerer als das Tempo, und danach fragen Mandanten am häufigsten. Anfragen eines Mandanten verlassen die Warteschlange nacheinander statt parallel, und eine Schlange von einem kann nicht gegen sich selbst laufen. Parallel abgefeuert können zwei Anfragen beide feststellen, dass das Access-Token abgelaufen ist, und die zweite startet einen Refresh, während die erste noch läuft. Auf manchen Systemen beendet das die Sitzung. Bei DATEV ist es schlimmer: Die Token werden entwertet, der Kunde muss also erneut durch die Authentifizierung für eine Verbindung, die einmal freigegeben werden und dann jahrelang laufen sollte. Die Ursache ist ein Schwall, der etwas zu schnell gesendet wurde, und die Wirkung trifft den, der sie am wenigsten verstehen kann. Die Sequenzierung nimmt den Wettlauf weg, statt danach zu wiederholen, und für viele DATEV-Anbindungen ist das und nicht das Tempo der Grund, warum die Warteschlange überhaupt genutzt wird.
Anfragen eines Kunden gehen nacheinander raus, sodass ein Token-Refresh nicht mitten in einen Schwall fallen kann.
Ein gleichmäßiger Strom im Tempo, das dieses System erlaubt, in Ihrer Sendereihenfolge, statt einer Spitze, die es mit 429 beantwortet.
Hier arbeiten zwei Ebenen, und sie müssen auseinandergehalten werden. Auf Maesns Seite: kein eigenes Limit auf dem Hinweg, Taktung zu jedem Ziel, Sequenzierung je Mandant. Auf Ihrer Seite: Ein Zielsystem kann weiterhin 429 antworten, aus Gründen außerhalb dieses Stroms, und wenn es das tut, bekommen Sie ein standardisierter Fehlertyp für genau diesen Fall plus dokumentierte Retry-Regel, eine anfängliche Wartezeit von einer Minute, die sich mit jedem Versuch verdoppelt. Was Maesn abfängt, ist der Teil, den Sie sonst modellieren würden. Was Sie erreicht, ist der Teil, der wirklich eine Entscheidung braucht.
Manche Arbeit ist nicht in einer Anfrage fertig
Ein Dokument hochzuladen, einen Buchungsvorschlag zu buchen oder einen Stapel Buchungssätze zu schreiben kann länger dauern, als eine Anfrage offen bleiben sollte. Diese Vorgänge antworten mit einer Aufgabe statt mit einem Ergebnis.
Eine Aufgabe zum Verfolgen
Ein asynchroner Vorgang antwortet sofort mit einer taskId, statt die Verbindung offen zu halten, bis das System fertig ist.
Teildaten sofort
Wo der Vorgang es unterstützt, trägt schon die erste Antwort das Objekt, das Sie gesendet haben, samt taskId daneben.
Ein Status, mit dem Sie arbeiten können
Das Verfolgen der Aufgabe liefert ihren Status und, sobald das System fertig ist, das angelegte Objekt unter responseData.
Was geschah, nicht nur dass es endete
Ein information-Array trägt die Meldungen, die das System gemeldet hat, je mit Dateinamen, Zeitstempel und Typ.
"data": {"status": "SUCCESS","information": [{"filename": "Invoice_V30","message": "The document hasbeen received.","type": "information"}],"responseData": { … }}
Die Mechanik ist überall dieselbe, wo sie greift. Der Antwortrumpf trägt eine taskId, Sie übergeben sie an GET /asyncTask, und Sie bekommen den Stand der Arbeit zurück sowie das Objekt, das das System angelegt hat, sobald es fertig ist. Die Endpunkte unten sind die, die sich heute so verhalten.
Welche Vorgänge das sind, ist nicht ganz Maesns Wahl. Eine synchrone Anfrage lässt sich immer asynchron machen; umgekehrt geht es gar nicht, wo ein Zielsystem also asynchron antwortet, bildet die Unified API das ab, statt so zu tun, als bliebe die Leitung offen. Das ist meist ein Schreibvorgang, denn Daten einzugeben ist die langsame Hälfte und die, die in Massen ankommt, während ein Lesezugriff sich normalerweise in einem Zug erledigen lässt. AbaConnect ist die Ausnahme, die man kennen sollte: Fragt man es nach einem Kontakt, kommt eine Kennung zurück und nicht der Kontakt, und der Satz wird mit einem späteren Aufruf abgeholt, sobald das System sich als fertig meldet.
Eine Aufgabe abzufragen ist die einfache Variante und oft die richtige innerhalb eines Laufs, den Sie ohnehin nach Zeitplan fahren. Sie ist nicht die einzige. Wo ein Zielsystem einen Schreibvorgang auf seiner Seite asynchron verarbeitet, also bei Systemen, bei denen Sie sonst senden, warten und den Ausgang abfragen würden, kann Maesn Ihnen das Ergebnis als Webhook-Event mitteilen, Erfolg oder Fehlschlag, das Warten verlässt Ihren Code also vollständig.
Volumen ist nicht mehr Ihre Modellierungsaufgabe
- Je System und Einheit einen Limiter bauen
- Fenster, Credits und Gleichzeitigkeit nachhalten
- Aufrufe um Token-Refreshes herum serialisieren
- Verbindungen für langsame Schreibvorgänge offen halten
- Den Schwall senden, Maesn taktet ihn aus
- Die Limits sind publiziert, nicht geraten
- Anfragen je Kunde sequenziert
- Lange Vorgänge antworten mit einer taskId
Rate-Limits sind der Teil einer Anbindung, der im Test funktioniert und im Betrieb scheitert. Zehn Rechnungen benehmen sich; der Monatsabschluss mit zehntausend nicht, und die Lösung ist dann eine Warteschlange, ein Limiter und eine Retry-Regel je System, geschrieben von dem, der gerade Bereitschaft hat. Jedes neue System, nach dem Ihre Kunden fragen, bringt weitere Zahlen und eine weitere Einheit in diese Maschinerie, und nichts davon ist das Produkt, das Sie bauen wollten.
Weil Taktung, Reihenfolge und Aufgabenverfolgung zu Maesn gehören, sammelt sich diese Maschinerie auf Ihrer Seite nicht an. Sie senden, was Sie haben, wenn Sie es haben. Das System, das Ihr Kunde als nächstes wählt, ändert das Tempo auf der Leitung, nicht den Code, der die Anfragen erzeugt hat. Das ist der Teil, den Produkt- und Entwicklungsteams nie zweimal bauen müssen.
Häufige Fragen
Drosselt Maesn meine Anfragen?
Was passiert, wenn ich mehr Anfragen sende, als ein Zielsystem erlaubt?
Wie unterschiedlich sind die Limits zwischen den Systemen?
Was ist eine asynchrone Aufgabe?
Welche Endpunkte unterstützen asynchrone Vorgänge?
Muss ich das Ergebnis abfragen?
Warum kann paralleles Senden die Authentifizierung zerlegen?
Macht die Taktung meine Anbindung langsamer?
Wo schlage ich das Limit eines bestimmten Systems nach?
Einmal bauen, auf der Unified API.
Sehen Sie, wie Asynchronous Processing für Ihre Integration funktioniert, oder steigen Sie in die technische Referenz ein.