Dateistapel mit kontrollierter Nebenläufigkeit verarbeiten

Warum nicht alles auf einmal gesendet werden sollte

Wenn Sie viele Dateien automatisiert verarbeiten, kann es schwierig werden, den Überblick über alle gleichzeitig gesendeten Anfragen zu behalten: Was ist abgeschlossen, was läuft noch und was ist fehlgeschlagen? Bei einer plötzlichen Vielzahl von Anfragen lässt sich außerdem nicht sicher feststellen, was passiert ist, wenn der Prozess unterbrochen wird. Eine Warteschlange mit einer Obergrenze für aktive Aufgaben und einem Status pro Datei kann helfen, die Arbeit zu organisieren. Das sind jedoch Entscheidungen für Ihre Integration und kein Verhalten, das jede API garantiert.

APIs bieten unterschiedliche Modelle. Mit der [OpenAI Batch API](https://help.openai.com/es-es/articles/9197833-batch-api-faq) können Anfragen zur asynchronen Verarbeitung eingereicht werden. Microsoft dokumentiert Batch-Anfragen für Abfragen und Vorgänge in der [SharePoint Online REST/OData API](https://learn.microsoft.com/es-es/sharepoint/dev/sp-add-ins/make-batch-requests-with-the-rest-apis). Diese Beispiele haben unterschiedliche Anwendungsbereiche und legen keine gemeinsame Regel für die Nebenläufigkeit anderer Dienste fest.

• Prüfen Sie zuerst die Dokumentation des verwendeten Endpunkts.
• Ordnen Sie jede Aufgabe eindeutig einer Datei zu.
• Trennen Sie dokumentierte API-Funktionen von den Entscheidungen für Ihre Warteschlange.

Vor dem Start: Den API-Vertrag lesen

Prüfen Sie, welche Eingaben der Endpunkt annimmt, welche Antworten er zurückgibt und ob das Ergebnis direkt geliefert oder asynchron verarbeitet wird. Achten Sie auch darauf, ob die Dokumentation Grenzwerte, Kennungen zur Statusabfrage oder Bedingungen für die Wiederholung eines Vorgangs nennt. Wenn ein Verhalten nicht festgelegt ist, sollten Sie es nicht voraussetzen: Fragen Sie beim Anbieter nach oder führen Sie einen kontrollierten Test durch.

Halten Sie diese Bedingungen in einem Integrationsprofil fest und unterscheiden Sie zwischen der Annahme einer Anfrage und dem Abschluss der Aufgabe. Apification ermöglicht die Integration von Cloud und seinen Diensten über REST API, OpenAPI und Webhooks. Das bedeutet nicht, dass alle Dienste dieselben Grenzwerte, Statusangaben oder Wiederholungsrichtlinien haben. Prüfen Sie die Referenzdokumentation des jeweiligen Dienstes.

• Endpunkt, Methode, Eingabeformat und erwartete Antwort festhalten.
• Nur dokumentierte Grenzwerte und Wiederholungsregeln notieren.
• Ermitteln, welche Antwort die Annahme und welche den Abschluss bestätigt.

Eine Warteschlange mit Status pro Datei entwerfen

Als Designentscheidung für Ihre Anwendung können Sie jede Datei als eigenständige Aufgabe abbilden. Speichern Sie eine interne Kennung, den Verweis auf die Datei und ihre Parameter; erfassen Sie außerdem den lokalen Status, die Versuche und das relevante Ergebnis oder den Fehler. Gibt die API eine Remote-Kennung zurück, kann deren Speicherung die Nachverfolgung erleichtern, sofern der Dienst eine Statusabfrage dokumentiert.

Verwenden Sie lokale Statusangaben mit eindeutiger Bedeutung, zum Beispiel: ausstehend, in Bearbeitung, abgeschlossen und Prüfung erforderlich. Stellen Sie sie nicht als Status des Anbieters dar, es sei denn, dessen Dokumentation definiert sie entsprechend. Durch ihre dauerhafte Speicherung kann Ihre Anwendung nach einer Unterbrechung unvollständige Aufgaben erkennen. Daraus allein lässt sich jedoch nicht ableiten, ob ein entfernter Vorgang tatsächlich ausgeführt wurde. Schützen Sie beim Speichern von Protokollen Geheimnisse und Zugangsdaten.

• Das Ergebnis jeder Aufgabe erfassen, nicht nur die Gesamtzahl des Stapels.
• Lokale Statusangaben von den durch die API zurückgegebenen Status unterscheiden.
• Den zur Untersuchung nötigen Kontext speichern, ohne Geheimnisse zu protokollieren.

Nebenläufigkeit auswählen und anpassen

Ohne Kenntnis der API und ihrer Bedingungen lässt sich kein allgemeingültiger Startwert empfehlen. Als Designleitlinie sollten Sie die Zahl gleichzeitig ausgeführter Aufgaben konfigurierbar machen und zunächst mit einer kleinen Last testen. Beobachten Sie die Antworten und alle vom Anbieter mitgeteilten Einschränkungen. Erhöhen oder verringern Sie den Grenzwert nur im Einklang mit den dokumentierten Regeln und Ihren Testergebnissen.

Die Gesamtgröße des Stapels und die Zahl gleichzeitig ausgeführter Aufgaben sind zwei unterschiedliche Dinge: Ein großer Stapel kann in kleineren Gruppen verarbeitet werden. Wenn Ihre Architektur mehrere Verbraucher einsetzt, legen Sie fest, wie der gemeinsame Grenzwert koordiniert wird. Gehen Sie nicht davon aus, dass jeder Verbraucher einzeln über die gesamte von der API erlaubte Kapazität verfügt.

• Mit wenigen Elementen und einem konfigurierbaren Grenzwert beginnen.
• Den Grenzwert anhand der Dokumentation und der beobachteten Antworten anpassen.
• Die gemeinsame Aktivität aller Verbraucher berücksichtigen.

Fehler klassifizieren und Wiederholungen begrenzen

Klassifizieren Sie Fehler anhand der Antworten und Regeln der jeweiligen API. Bei manchen Fehlern müssen möglicherweise die Datei oder die Parameter korrigiert werden; andere können eine erneute Ausführung rechtfertigen, sofern die Dokumentation dies zulässt. Leiten Sie keine allgemeingültige Richtlinie allein aus dem Fehlertext ab. Speichern Sie den Fehlercode und den relevanten Kontext zur Diagnose, ohne sensible Daten offenzulegen.

Als Designentscheidung können Sie für Fälle, in denen eine Wiederholung zulässig ist, eine Höchstzahl von Versuchen und eine Wartezeit zwischen ihnen festlegen. Bleibt der Status eines Vorgangs unklar, beweist ein Timeout nicht, dass der Dienst ihn nicht verarbeitet hat: Senden Sie die Anfrage nicht blind erneut. Wenn die API einen Idempotenzmechanismus dokumentiert, halten Sie sich an dessen Bedingungen. Andernfalls sollten Sie nicht annehmen, dass eine Wiederholung sicher ist.

• Für jeden Fehler entscheiden, ob eine Wiederholung, Korrektur oder Prüfung angebracht ist.
• Jeden Versuch protokollieren und unbegrenzte Wiederholungsschleifen vermeiden.
• Bei Anfragen mit unklarem Ergebnis besonders vorsichtig vorgehen.

Einen unterbrochenen Stapel fortsetzen

Laden Sie beim Neustart Ihrer Anwendung den gespeicherten Status und behalten Sie abgeschlossene Aufgaben bei. Prüfen Sie bei Aufgaben, die noch in Bearbeitung waren, ob die API eine dokumentierte Möglichkeit bietet, ihren Status anhand einer Kennung abzufragen. Lässt sich die Unsicherheit nicht auflösen, legen Sie für solche Fälle eine ausdrückliche Richtlinie fest oder leiten Sie sie zur Prüfung weiter, statt sie automatisch erneut zu senden.

Verwenden Sie für jede Aufgabe eine stabile Identität und behandeln Sie Änderungen an Dateien oder Parametern als unterscheidbare Aufträge. Mit Apification können Sie den Verlauf von Cloud-Elementen prüfen, frühere Versionen herunterladen und Inhalte wiederherstellen. Diese Funktionen unterstützen die Überprüfung von Änderungen in Cloud, ersetzen jedoch nicht die Nachverfolgung von Anfragen und garantieren nicht, dass ein API-Vorgang idempotent ist.

• Abgeschlossene Aufgaben überspringen und Aufgaben prüfen, die noch in Bearbeitung waren.
• Eine verlorene Antwort nicht als Beweis dafür ansehen, dass der Vorgang fehlgeschlagen ist.
• Änderungen an Eingaben oder Parametern protokollieren, damit Aufträge unterscheidbar bleiben.

Betriebsablauf und Tests

Ein möglicher Ablauf: Dateien validieren, für jedes Element eine gespeicherte Aufgabe erstellen, die Aufgaben mit dem festgelegten Grenzwert verarbeiten und jede Antwort protokollieren. Zeigen Sie zum Abschluss die Ergebnisse an und unterscheiden Sie zwischen abgeschlossenen Aufgaben, Fällen mit Korrekturbedarf und weiterhin unklaren Aufgaben. Dies sind Designentscheidungen für Ihre Integration und keine Garantien für das Verhalten einer externen API.

Testen Sie vor dem produktiven Einsatz Unterbrechungen und unklare Antworten, zum Beispiel ein Timeout oder einen Ausfall zwischen dem Senden und dem Protokollieren des Ergebnisses. Prüfen Sie, ob die Anwendung den zur Untersuchung nötigen Kontext behält und ob ihre Richtlinie verhindert, dass abgeschlossene Aufgaben oder solche mit unbekanntem Ergebnis automatisch erneut gesendet werden. Richten Sie jeden Fall nach den dokumentierten Möglichkeiten des Dienstes aus. Apification bietet einen geführten Assistenten zur Verarbeitung von Dokumenten, Bildern, Videos, Audiodateien und Daten sowie Optionen zur API-Integration. Prüfen Sie in der Dokumentation des Dienstes, welche Vorgänge über die API verfügbar sind.

• Eingaben validieren und festlegen, was den Abschluss einer Aufgabe ausmacht.
• Unterbrechungen und unklare Status testen, ohne das Verhalten des Anbieters vorauszusetzen.
• Zum Abschluss des Stapels ausstehende Aufgaben, behebbare Fehler und prüfbedürftige Fälle kennzeichnen.

Häufige Fragen