Omgaan met responslimieten van de gegevensexport-API

Wat de grenzen zijn

Er gelden twee soorten beperkingen voor verzoeken waarin een datumbereik is opgenomen:

Maximale datumperiode

Indien het tijdsbestek tussen startDateTime en endDateTime langer is dan zeven dagen, retourneert de API een 400-antwoord met de foutcode ERR_DATE_RANGE_EXCEEDED. Verminder de omvang van het gevraagde tijdvenster en dien het verzoek opnieuw in.

Maximale grootte van het antwoord

De maximaal ondersteunde grootte van een responsbestand is 6 MB, wat ruim voldoende zou moeten zijn om de gegevens van bijna 10.000 taken te bevatten. Indien de gegevens die overeenkomen met een verzoek de maximale responsgrootte zouden overschrijden, retourneert de API een 413-respons met de foutcode ERR_RESPONSE_LIMIT_EXCEEDED. De inhoud van het antwoord bevat een maxJobs-waarde die de geldende limiet aangeeft. Om het probleem op te lossen, kunt u de datumperiode beperken, minder printers aanvragen of beide, en de aanvraag vervolgens opnieuw indienen.

Verzoeken om binnen de gestelde grenzen te blijven

Om een integratie te ontwerpen die betrouwbaar binnen de responslimieten blijft, dient u rekening te houden met de volgende factoren:

• Aantal taken per printer. Een printer met hoge doorvoercapaciteit en continue invoer kan veel meer taken per uur verwerken dan een printer voor losse vellen met een laag volume. Als u beide typen in uw machinepark combineert, bepalen de printers met een hoog printvolume hoe kort uw tijdsvensters moeten zijn.
• Aantal printers per aanvraag. Elk verzoek kan meerdere printerId -waarden bevatten. Het is handig om meerdere printers in één verzoek samen te voegen, maar elke extra printer vergroot de omvang van het antwoord en de kans dat de limiet wordt overschreden.
• Tijdstip van de dag. Indien uw bedrijf in ploegen werkt, concentreren de taken en statuswijzigingen zich op bepaalde uren. Een periode van 24 uur kan zeer uiteenlopende volumes opleveren, afhankelijk van het tijdstip waarop die 24 uur beginnen en eindigen.
• Aantal toegestane herpogingen. Indien een verzoek mislukt met de foutcode ERR_RESPONSE_LIMIT_EXCEEDED, dient uw integratie het verzoek op te splitsen en het opnieuw te proberen. Het ontwerpen met het oog op kleinere vensters is doorgaans minder complex dan het implementeren van dynamische verdeling.

Aanbevolen patronen

De volgende patronen zijn geschikt voor veelvoorkomende integratiescenario’s:

Nachtelijk overzicht voor rapportage

Voer één keer per dag een geplande taak uit waarbij de gegevens van de afgelopen 24 uur worden opgevraagd, printer voor printer. Dit patroon is eenvoudig te implementeren, kan bij een mislukking gemakkelijk opnieuw worden uitgevoerd en zorgt ervoor dat elk antwoord kort blijft. Verwerk de antwoorden per printer in uw vervolgproces.

Uurlijkse gegevensopname voor dashboards die bijna in realtime werken

Voer één keer per uur een geplande taak uit waarmee in één verzoek de gegevens van het voorgaande uur voor alle printers worden opgevraagd. Door het gebruik van uurvensterperioden blijven de responsgroottes beperkt, zelfs bij drukkers met een hoog drukvolume. Indien u over een groot wagenpark beschikt, verzoekt u erom de printers in groepen aan te vragen in plaats van allemaal tegelijk.

Achteraf invoeren van historische gegevens

Om een datawarehouse te vullen met historische gegevens, doorloopt u het tijdsbereik in vensters van vaste grootte (bijvoorbeeld zes uur per verzoek) en uw printers in kleine groepen. Verwerk één venster tegelijk en sla de resultaten op voordat u naar het volgende venster gaat. Indien een venster de foutmelding ERR_RESPONSE_LIMIT_EXCEEDED weergeeft, verdeel dat venster dan in twee gelijke delen en probeer het opnieuw met beide delen.

Huidige status van de printer ten behoeve van de bewaking

Om de huidige status van elke printer in uw printerpark te controleren zonder de geschiedenis op te halen, roept u /printer-states aan met currentState=true. Het antwoord bevat één rij per motor en wordt niet beïnvloed door de datumperiode, zodat één enkel verzoek de gehele vloot kan omvatten.

Omgaan met fouten in verband met responslimieten in uw integratie

Wanneer u een 413-antwoord ontvangt met de foutcode ERR_RESPONSE_LIMIT_EXCEEDED, voer dan een of meer van de volgende handelingen uit voordat u het verzoek opnieuw probeert:

• Verkort het tijdsvenster. Het venster in tweeën splitsen is een betrouwbare strategie; als het gehalveerde verzoek nog steeds mislukt, splitst u het opnieuw.
• Verminder het aantal printerId -waarden in het verzoek. Indien één printer verantwoordelijk is voor het grootste deel van het printvolume, dient u die printer afzonderlijk aan te vragen.
• Indien het verzoek betrekking heeft op een actueel momentopname in plaats van op een historisch overzicht, gebruikt u currentState=true op /printer-states om het door datumbereiken bepaalde volume volledig te vermijden.

Probeer hetzelfde verzoek niet opnieuw uit te voeren zonder de parameters te wijzigen. De API levert geen gedeeltelijke resultaten op, dus een herhalingspoging zonder aanpassingen zal opnieuw mislukken.