Umgang mit den Antwortbeschränkungen der Datenexport-API

Wo die Grenzen liegen

Für Abfragen, die einen Datumsbereich enthalten, gelten zwei Arten von Einschränkungen:

Maximaler Datumsbereich

Wenn der Zeitraum zwischen startDateTime und endDateTime sieben Tage überschreitet, gibt die API eine 400-Antwort mit dem Fehlercode ERR_DATE_RANGE_EXCEEDED zurück. Verringern Sie die Größe des angeforderten Zeitfensters und senden Sie die Anfrage erneut ab.

Maximale Antwortgröße

Die maximal unterstützte Größe einer Antwortdatei beträgt 6 MB, was ausreichen sollte, um die Daten von fast 10.000 Jobs zu speichern. Sollten die Daten, die einer Anfrage entsprechen, die maximale Antwortgröße überschreiten, gibt die API eine 413-Antwort mit dem Fehlercode ERR_RESPONSE_LIMIT_EXCEEDED zurück. Der Antworttext enthält einen maxJobs-Wert, der die geltende Obergrenze angibt. Um das Problem zu beheben, grenzen Sie den Datumsbereich ein, fordern Sie weniger Drucker an oder tun Sie beides, und senden Sie die Anfrage erneut ab.

Planungsanträge, die innerhalb der Grenzen bleiben sollen

Um eine Integration zu entwickeln, die zuverlässig innerhalb der Antwortgrenzen bleibt, sollten Sie folgende Faktoren berücksichtigen:

• Auftragsvolumen pro Drucker. Ein Durchlaufdrucker mit hohem Durchsatz kann pro Stunde weitaus mehr Jobs verarbeiten als ein Einzelblattdrucker mit geringem Durchsatz. Wenn Sie beide in Ihrem Gerätepark kombinieren, bestimmen die Drucker mit hohem Druckvolumen, wie kurz Ihre Zeitfenster sein müssen.
• Anzahl der Drucker pro Anfrage. Jede Anfrage kann mehrere printerId-Werte enthalten. Es ist zwar praktisch, mehrere Drucker in einer einzigen Anfrage zusammenzufassen, doch jeder zusätzliche Drucker erhöht die Antwortgröße und damit die Wahrscheinlichkeit, dass das Limit überschritten wird.
• Tageszeit. Wenn Ihr Betrieb im Schichtbetrieb läuft, konzentrieren sich Jobs und Statusänderungen auf bestimmte Stunden. Ein 24-Stunden-Zeitraum kann sehr unterschiedliche Volumina ergeben, je nachdem, wann diese 24 Stunden beginnen und enden.
• Toleranz für Wiederholungsversuche. Sollte eine Anfrage mit dem Fehler ERR_RESPONSE_LIMIT_EXCEEDED fehlschlagen, muss Ihre Integration die Anfrage aufteilen und einen erneuten Versuch unternehmen. Die Gestaltung für kleinere Fenster im Vordergrund ist in der Regel weniger komplex als die Umsetzung einer dynamischen Aufteilung.

Empfohlene Muster

Die folgenden Muster eignen sich gut für gängige Integrationsszenarien:

Nächtlicher Auszug für die Berichterstellung

Führen Sie einmal täglich einen geplanten Job aus, der die Daten der letzten 24 Stunden abruft, und zwar jeweils für einen Drucker nach dem anderen. Dieses Muster lässt sich einfach umsetzen, bei Fehlern leicht wiederholen und sorgt dafür, dass jede Antwort kurz bleibt. Führen Sie die Antworten für die einzelnen Drucker in Ihrem nachfolgenden Prozess zusammen.

Stündlicher Datenauszug für Kontrollanzeigen in nahezu Echtzeit

Führen Sie einmal pro Stunde einen geplanten Job aus, der in einem einzigen Aufruf die Daten der vergangenen Stunde für alle Drucker abruft. Durch stündliche Zeitfenster bleibt der Umfang der Antworten selbst bei Druckereien mit hohem Druckaufkommen gering. Sollten Sie über einen großen Fuhrpark verfügen, bestellen Sie die Drucker bitte in Gruppen und nicht alle auf einmal.

Nachträgliche Erfassung historischer Daten

Um ein Data Warehouse mit historischen Daten zu befüllen, durchlaufen Sie den Zeitbereich in Fenstern fester Größe (beispielsweise sechs Stunden pro Anfrage) und Ihre Drucker in kleinen Gruppen. Bearbeiten Sie jeweils ein Fenster nach dem anderen und speichern Sie die Ergebnisse, bevor Sie zum nächsten Fenster weitergehen. Sollte ein Fenster den Fehler ERR_RESPONSE_LIMIT_EXCEEDED auslösen, teilen Sie dieses Fenster in zwei Hälften und wiederholen Sie den Versuch mit den beiden Hälften.

Aktueller Druckerstatus zur Überwachung

Um den aktuellen Status jedes Druckers in Ihrem Bestand zu überwachen, ohne den Verlauf abzurufen, rufen Sie den Befehl /printer-states mit dem Parameter currentState=true auf. Die Antwort enthält eine Zeile pro Druckwerk und ist unabhängig vom Datumsbereich, sodass eine einzige Abfrage die gesamte Flotte abdecken kann.

Behandlung von Fehlern aufgrund von Antwortbeschränkungen in Ihrer Integration

Wenn Sie eine 413-Antwort mit dem Fehlercode ERR_RESPONSE_LIMIT_EXCEEDED erhalten, führen Sie eine oder mehrere der folgenden Maßnahmen durch, bevor Sie die Anfrage erneut versuchen:

• Verkürzen Sie das Zeitfenster. Das Fenster in zwei Hälften zu teilen, ist eine bewährte Strategie; sollte die halbierte Anfrage weiterhin fehlschlagen, teilen Sie sie erneut.
• Reduzieren Sie die Anzahl der printerId-Werte in der Anfrage. Falls ein Drucker den Großteil des Druckvolumens ausmacht, bestellen Sie diesen Drucker bitte separat.
• Sollte die Anfrage einen aktuellen Snapshot und keine Historie betreffen, verwenden Sie bitte currentState=true bei /printer-states, um datumsbereichsabhängige Datenmengen vollständig zu vermeiden.

Versuchen Sie nicht, dieselbe Anfrage erneut auszuführen, ohne die Parameter zu ändern. Die API gibt keine Teilergebnisse zurück, sodass ein unveränderter erneuter Versuch erneut fehlschlagen wird.