Welke Rate Limits kent Exact Online?
Exact Online kent een almaar groeiend aantal beperkingen aan het gebruik van de API, zogenaamde “rate limits”, zoals:
- een limiet aan API calls per dag, administratie en app;
- een limiet aan API calls per minuut, administratie en app;
- nieuwe limieten sinds 2021.
De oorspronkelijke rate limits - waarvan de beschreven foutmelding er 1 is - waren en zijn goed toepasbaar en oplosbaar. De nieuwe rate limits zijn niet op hun fraaist, mede door de onderlinge interactie.
Exact Online rate limit per dag
Exact Online kent per administratie (“divisie” en bij Invantive SQL “partitie”) en applicatie een limiet qua aantal aanroepen van de API per dag. Dit is een harde limiet; bij overschrijding kan er met de combinatie van app (“client ID”) en divisie geen succesvolle API-aanroep uitgevoerd worden tot het resetmoment. Het resetmoment ligt op de daggrens.
Het maximum aantal aanroepen per dag, division en app ligt meestal tussen de 5.000 en 50.000. Exact Online wil nog weleens apps die in hun perceptie te veel calls doen enorm terugzetten naar bijvoorbeeld 150 of 300 API calls per dag. Dit kan verwarring geven omdat het geval van 300 (API calls) ook een minuutlimiet is. Lees daarom de foutmeldingen zorgvuldig en vermeld altijd de foutcode itgenXXX999.
Andere rate limits op Exact Online
Daarnaast kent Exact Online nog meer zogenaamde “rate limiters”, waaronder een limiet per minuut en allerhande nieuwe rate limits zoals het interval tussen het vernieuwen van de autorisatie (zie Impact Exact Online API aanpassingen 1 juli 2021). Ook limieten worden naar verluidt gesteld aan de foutenrate; zie Triggering the new error rate limit active of 10 per app, endpoint, Exact Online division, user and hour en Impact analysis of 10 error messages per app, endpoint, division, user and hour.
Zie ook:
Hoe analyseer je een overschrijding van de dagelijkse rate limit?
Er zijn verschillende mogelijkheden om zelf een analyse uit te voeren hoe de 15.000 API calls op deze administratie verbruikt zij:
-
SessionIOs@DataDictionary: raadpleeg deze runtime beschikbare view met actueel API-gebruik
- Invantive Cloud sessie I/O’s: raadpleeg deze cumulatieve registratie van sessie I/O’s verzameld op Invantive Cloud
-
dc_table_partition_versions_r: raadpleeg deze view in de backing database (meestal SQL Server) om te achterhalen wat de echt grote gerepliceerde tabellen zijn op deze divisie (Invantive SQL-gebruik: “partitie”).
- de views beschreven op Analyseer Exact Online API gebruik met `RateLimits` of `SystemPartitions`.
SessionIOs@DataDictionary naar Excel-sheet
In de view SessionIOs@DataDictionary wordt elke afgeronde API-call bewaard.
De inhoud van SessionIOs@DataDictionary is vluchtig; bij afsluiten van het programma zijn de gegevens weg.
Een reeks van statements in het Exact Online replicatie-script zoals:
select *
from SessionIOs@DataDictionary
local export results as "c:\temp\mijn-ios.xlsx" format xlsx include technical headers
zorgt er voor dat een Excel-sheet beschikbaar is na de afloop van het programma met daarin elke uitgevoerde API-call. Filter hierin op de kolom PARTITION om de betrokken administratie te vinden.
Zorg er wel voor met local on error continue dat een foutmelding er niet toe leidt dat het replicatiescript meteen al bij de Exact Online foutmelding beëindigd wordt.
Invantive Cloud Sessie I/O’s
Op Invantive Cloud worden alle sessie I/O’s centraal geregistreerd. Ze zijn daar opvraagbaar via het scherm “Sessie I/O’s”. Na filtering zijn ze te downloaden als Excel, CSV of PDF. Ook kan doorgeklikt worden naar de individuele statements zoals dit statement op Exact Online:
Het scherm Sessie I/O’s in Invantive Cloud is helaas vaak niet bruikbaar meer. Ondanks dagelijkse compressie, worden per dag ruim 1 miljoen API calls vastgelegd verspreid over 20.000 bedrijven en 75 platformen. Door de beveiligingslagen zijn alleen de eigen sessie I/O’s zichtbaar, maar ze worden wel vrijwel geheel verwerkt bij een opvraging. Deze aantallen hadden we niet verwacht op zo’n korte termijn. Deze vraag was een trigger om de snelheid te verbeteren. De komende release zal naar verwachting een mogelijkheid hebben om door te klikken vanuit Organisatie en Overeenkomst naar de Sessie I/O’s, zodat er meteen gefilterd kan worden en de prestaties weer acceptabel worden.
Repository view dc_table_partition_versions_r
De view dc_table_partition_versions_r op basis van de Data Replicator tabel dc_table_partition_versions toont per combinatie van datacontainer, tabel, partitie (administratie/divisie) en versienummer de aantallen verwerkte rijen.
Door met een SQL-statement te filteren op de partitie kan vlot achterhaald worden welke tabellen in deze administratie erg groot zijn. Een kolom zoals tpn_count_rows geeft aan hoeveel rijen er in zitten. Ook zijn er kolommen beschikbaar met de historische waardes en de aangroei.
Om terug te rekenen naar het aantal API-calls is het nodig om eerst onderscheid te maken tussen de “seeding approach” in tpn_seeding_approach_used_code zijnde Trickle Loading (“T”) of Complete (“C”). Bij Trickle Loading zijn de Exact Online webhooks gebruikt, bij Complete is de volledige lijst opgehaald.
Elke mutatie via Trickle Loading kost tussen de 0.1 en 0.02 API-calls dankzij bundeling. De mutaties zijn te vinden door de kolommen tpn_count_rows_deleted, tpn_count_rows_inserted en tpn_count_rows_updated op te tellen.
In het geval van Complete zijn alle rijen geladen. Kijk dan naar de tabelnaam:
- Tabelnaam eindigt op “Bulk”: deel het totale aantal rijen door 1.000 voor het aantal API-calls.
- Tabelnaam eindigt op “Incremental”: neem de vaste waarde 5 als redelijke schatting voor deze Exact Online Sync API’s.
- Tabelnaam bevat “ExactOnlineXML”: deel het totale aantal rijen door 100 voor het aantal API-calls.
- Alle andere gevallen: deel het aantal rijen door 60 voor het aantal API-calls.
Hoe neem je de oorzaak van de overschrijding van de rate limit weg?
Na het analyseren welke tabellen relatief veel API-calls consumeren kan het aanvalsplan bepaald worden. Zonder volledigheid te willen nastreven zijn de volgende stappen aan te raden:
- Zijn er tabellen die wel dagelijks geladen worden maar niet meer nodig zijn omdat er bijvoorbeeld een
*Bulk of *Incremental-versie ook geladen wordt? Verwijder die met alter persistent cache drop... en controleer die replicatiescripts dat ze niet automatisch weer toegevoegd worden.
- Zijn er tabellen die vervangen kunnen worden door de
*Incremental tabellen zoals door TransactionLinesIncremental? Zo ja, vervang die.
- Zijn er tabellen die kunnen wisselen naar trickle loading zoals
PjtTimeTransactions (de projecturen hebben om onbekende reden geen Sync API)? Zo ja, zet dan trickle loading aan.
In overige gevallen raden we een kort consult aan vanuit Invantive om de situatie te analyseren en te verbeteren.
Hoe beperk je de schade van rate limits?
Meestal overschrijden maar enkele administraties (“divisies”) in een grote groep de maximale limiet, bijvoorbeeld omdat er enorm veel urenregistraties op staan die blind elke dag volledig opgehaald worden.
Echter, een foutmelding bij het laden kan er toe leiden dat een (mogelijk groot) deel van de overige administraties niet verwerkt wordt. Het is dan aan te raden om met een use statement eerst alle divisies te selecteren behalve de problematisch en daarna de replica bij te werken:
use select code, 'eol' from systemdivisions@eol where code not in (123456, 234567)
alter persistent cache refresh
Daarna kan geprobeerd worden te laden wat kan:
use 123456@eol, 234567@eol
alter persistent cache refresh
Eventueel kunnen de tabellen ook op volgorde van benodigde hoeveelheid API-calls bijgewerkt worden via een alter persistent cache-statement.
