Exact Online naar Azure: paginering, API-limieten en historie
Om 3.30 uur 's nachts weigert Exact Online de volgende pagina met verkoopfacturen van de Belgische vestiging. Het dagbudget aan aanroepen is op. Het is de eerste keer dat de groothandel zijn drie administraties volledig laadt.
Een database geef je een vraag en je krijgt alle rijen terug. Exact Online antwoordt in pagina's, begrenst het aantal aanroepen per minuut en per dag en laat de toegang na ongeveer 10 minuten verlopen. Elke administratie is bovendien een eigen omgeving met een eigen aanmelding.
Wie dat per tabel met de hand bouwt, is daar bij 180 tabellen lang mee bezig. Hieronder richt Sanne, de data-engineer van de groothandel, de koppeling in. Na de eerste volledige laadactie haalt Yres elke nacht alleen op wat is gewijzigd.
Gepubliceerd: · Laatst bijgewerkt: · Door Daniel Sanders, architect van Yres en oprichter van Plainwater
Waarom is een API-bron anders dan een database?
Een API levert data in porties, onder limieten en met een toegang die verloopt. Een database levert een tabel in één keer, zolang de verbinding openstaat.
De groothandel voert drie administraties in Exact Online: de Nederlandse groothandel, de Belgische vestiging en het eigen transportbedrijf. Tot nu toe kwam het boekhoudpakket als database binnen, zodat Sanne een tabel in één keer kon opvragen. Bij Exact Online verschilt dat op vier punten.
Pagina's. Exact beantwoordt elke vraag met een pagina rijen en een verwijzing naar de volgende pagina. Een klanttabel van 5.000 rijen kost daarmee tientallen vragen achter elkaar in plaats van één.
Limieten. Exact begrenst het aantal aanroepen per app en per administratie, met een limiet per minuut en een limiet per dag. Die limieten publiceert Exact zelf. Wie te vaak aanklopt, krijgt een weigering terug in plaats van rijen. Een laadactie die daarop niet is voorbereid, stopt halverwege een tabel. Niemand weet dan welke pagina's al binnen zijn.
Toegang. Exact werkt met een toegangsbewijs dat na ongeveer 10 minuten verloopt, terwijl nachtelijk laden een paar uur kan duren. Je hebt dus een tweede sleutel nodig waarmee je een nieuw bewijs ophaalt. Ook dat vernieuwen begrenst Exact. Wie het te vaak doet, wordt eveneens geweigerd.
Administraties. Een aanmelding bij Exact hoort bij één administratie. Drie administraties zijn dus drie aanmeldingen, elk met eigen sleutels en een eigen teller voor de limieten. Wat voor een database één verbinding is, is voor Exact Online drie keer alles.
Wat er gebeurt bij de eerste keer volledig laden
Sanne maakt in het beheerscherm drie koppelingen aan, één per administratie. Per koppeling vult ze de sleutels van de Exact-app in en logt ze één keer in bij Exact. Yres haalt daarna het toegangsbewijs en de vernieuwingssleutel op en bewaart ze in de database van de groothandel. De sleutels van de app zelf gaan naar de sleutelkluis in het Azure-abonnement van de groothandel. Niets daarvan staat bij Yres.
Daarna leest Yres de structuur uit. Exact verdeelt zijn API in diensten, zoals financieel, verkoop, inkoop, voorraad en personeel. Yres loopt een vaste lijst van ruim 50 van die diensten af. Van elke dienst leest het het structuurdocument: welke gegevenssets er zijn, met welke velden en welke types. Elke gegevensset wordt in Yres een tabel. De structuur van een dienst wordt pas zichtbaar als hij volledig is ingelezen. Diensten die niet meer bestaan, worden opgeruimd.
Samen leveren die diensten enkele honderden gegevenssets per administratie op. Sanne zet er per administratie 60 aan die de groothandel nodig heeft, samen 180 tabellen. Per tabel kiest ze meteen de laadwijze die alleen wijzigingen ophaalt. Ze wijst de kolom aan waarin Exact de datum van de laatste wijziging bijhoudt. Veel gegevenssets van Exact hebben zo'n kolom. Een gegevensset met een oplopend wijzigingsnummer werkt ook.
De eerste nacht is er nog geen watermerk, dus vraagt Yres per tabel alles op. Per tabel gaat dat zo:
- Leegmaken. Yres maakt de landingszone voor die tabel leeg.
- Toegang controleren. Yres kijkt of het toegangsbewijs nog minstens drie minuten geldig is. Zo niet, dan wacht het tot het bewijs is verlopen en haalt het met de vernieuwingssleutel een nieuw bewijs op.
- Pagina's volgen. Yres vraagt de eerste pagina op. Exact antwoordt met de rijen en de link naar de volgende pagina. Yres volgt die link tot er geen volgende meer is, met een seconde pauze tussen twee pagina's.
- Tellen. Elke rij krijgt het tijdstip van laden mee en het aantal gekopieerde rijen gaat naar het logboek.
- Samenvoegen. De motor neemt het over: vergelijken met de vingerafdrukken, versies afsluiten en toevoegen. Hoe dat werkt, staat in ons artikel over historie bijhouden bij honderden tabellen.
De werkstroom doet dit voor vijf tabellen tegelijk. Om 3.30 uur 's nachts is het dagbudget van de Belgische administratie op. Exact weigert de volgende pagina van de tabel met verkoopfacturen. Yres probeert het in dezelfde nacht niet opnieuw. De tabel staat in het logboek als mislukt, met de stap waar het misging, terwijl de andere tabellen doorlopen.
Aan het einde van de nacht staat de laadactie als geheel ook als mislukt, omdat er één tabel ontbreekt. Het monitoringscherm laat zien welke. De tabellen die wel klaar zijn, staan in de historietabel. De mislukte tabel heeft nog geen watermerk en begint de volgende nacht van voren af aan.
Sanne spreidt daarom de eerste laadactie. Per administratie zet ze een deel van de tabellen tijdelijk uit. Een tabel die uitstaat, blijft ingericht en loopt alleen niet mee. Elke nacht zet ze een volgend deel aan, zodat na een week alle 180 tabellen een eerste keer zijn geladen.
Daarna: alleen wat gewijzigd is
Na een geslaagde eerste laadactie heeft elke tabel een watermerk: de hoogste wijzigingsdatum die in de historietabel staat. De motor zet het pas nadat de samenvoeging is afgerond. Niemand hoeft er iets voor in te stellen.
Vanaf dan vraagt Yres elke nacht per tabel alleen de rijen op die sinds het watermerk zijn gewijzigd. De vraag aan Exact luidt 'vanaf en met' dat moment. Rijen die op dat moment zelf zijn gewijzigd, komen dus nog een keer mee. De motor vergelijkt ze met de versie die er al staat en maakt alleen bij een echte wijziging een nieuwe versie. Voor de klanttabel van de Nederlandse administratie is dat een handvol rijen per nacht in plaats van 5.000. De verhuizing van Bakkerij Ter Horst van 2 oktober komt als één rij binnen, op één pagina.
Het watermerk schuift pas op als de hele tabel is verwerkt. Weigert Exact halverwege een pagina, dan blijft het watermerk staan waar het stond. Het monitoringscherm meldt dat het niet is opgeschoven. De volgende nacht vraagt Yres opnieuw om alles sinds dat moment, zonder dat er iets hersteld hoeft te worden. Het watermerk volgt de inhoud van de tabel. Een mislukte poging laat het met rust. Ons artikel over terugdraaien gaat daar verder op in.
Het dagbudget van Exact wordt zo nauwelijks meer aangesproken. Een deltanacht van de drie administraties kost een fractie van de eerste laadactie. De limiet per minuut blijft in beeld: Yres wacht een seconde tussen twee pagina's van dezelfde tabel, al lopen er wel tot vijf tabellen tegelijk.
| Wat de API vraagt | Wat Yres doet | Waar je het terugziet |
|---|---|---|
| Antwoorden in pagina's | Volgt de link naar de volgende pagina tot er geen meer is, met een seconde pauze | Aantal gekopieerde rijen per tabel in het logboek |
| Limiet per minuut | Eén pagina per seconde per tabel, tot vijf tabellen tegelijk | Tijdlijn per tabel in het monitoringscherm |
| Limiet per dag | Delta per tabel op de wijzigingsdatum, zodat een nacht een fractie van de eerste keer laden kost | Een weigering staat als mislukte stap bij die tabel. Het watermerk blijft staan |
| Toegang die na 10 minuten verloopt | Controle vóór elke tabel. Wachten tot het bewijs is verlopen, dan vernieuwen met de bewaarde sleutel | Een mislukte vernieuwing staat als mislukte stap in het logboek |
| Eén administratie per aanmelding | Eén koppeling per administratie, elk met eigen sleutels en eigen tabellen | Drie bronnen in het beheerscherm, drie keer dezelfde tabellen in het datawarehouse |
| Nieuwe velden na een update van Exact | Metadata verversen leest de structuurdocumenten opnieuw. De kolom loopt daarna mee, zoals bij elke andere bron | Vergelijking van structuur en tabellen na elke verversing |
| Een tabel die halverwege mislukt | Geen nieuwe poging in dezelfde nacht. De andere tabellen lopen door en het watermerk blijft staan | Tabel als mislukt in het monitoringscherm, de laadactie als geheel ook |
Wie logt er 's nachts in?
Niemand. Sanne heeft per administratie één keer ingelogd. Sindsdien bewaart Yres per koppeling het kortlevende toegangsbewijs, met het moment tot wanneer het geldig is, en de vernieuwingssleutel waarmee een nieuw bewijs wordt opgehaald.
De sleutels van de Exact-app zelf staan in de sleutelkluis van het abonnement. Vóór elke tabel doorloopt Yres deze stappen:
- Kijken. Yres bekijkt het bewaarde bewijs. Is het nog minstens drie minuten geldig, dan gebruikt Yres het.
- Wachten. Zo niet, dan wacht Yres tot het bewijs is verlopen. Dat wachten is bewust, want Exact begrenst ook hoe vaak je mag vernieuwen. Yres vernieuwt dus pas als het echt moet.
- Vernieuwen. Met de vernieuwingssleutel vraagt Yres een nieuw bewijs aan. Het nieuwe bewijs en de nieuwe sleutel gaan weer de database in, met een geldigheid van ongeveer 10 minuten.
Een leeg of onbruikbaar antwoord van Exact overschrijft nooit een sleutel die nog werkte. Het verversen van de metadata doet dezelfde controle voordat het begint.
Mislukt het vernieuwen, bijvoorbeeld omdat iemand de koppeling in Exact heeft ingetrokken, dan staat die stap als mislukt in het logboek. De data van die administratie komt die nacht niet binnen. Iemand moet dan opnieuw inloggen via het beheerscherm. Dat is het enige moment waarop een mens eraan te pas komt.
Wanneer gebruik je het?
Yres voor Exact Online gebruik je als je historie nodig hebt, meerdere administraties combineert of Exact naast andere bronnen zet. Bij de groothandel speelt alle drie.
Drie administraties in één rapport. De directie wil de omzet van Nederland, België en het transportbedrijf in één overzicht. De kredietlimiet van De Jong Transport moet kloppen met wat gold op het moment van elke order. Elke administratie landt als eigen set tabellen in het datawarehouse, met historie. Sanne bouwt daar één view overheen. Een rechtstreekse koppeling per administratie geeft drie losse overzichten zonder verleden.
Exact naast een andere bron. Het personeelssysteem levert 40 tabellen, waaronder de uren van de chauffeurs van het transportbedrijf. De kosten staan in Exact. Beide bronnen laden in dezelfde nacht, in dezelfde database en met dezelfde motor. Het rapport over kosten per rit kan ze zo combineren.
Wisselen van pakket. De Belgische vestiging stapt volgend jaar over op een ander boekhoudpakket. De historie uit Exact blijft in het datawarehouse staan. De nieuwe bron komt ernaast en de rapporten blijven werken.
Waar het ophoudt
- Een geweigerde pagina wordt in dezelfde nacht niet opnieuw geprobeerd. De tabel staat als mislukt, de rest loopt door
- Een venster van een dag extra teruglezen kan bij andere bronnen, maar niet voor de wijzigingsdatum van Exact Online
- Elke administratie krijgt eigen tabellen. Het samenvoegen tot één overzicht is een view daarboven
- De limieten stelt Exact. Yres gaat er zuinig mee om, maar kan er niet overheen
Veelgestelde vragen
Hoe laadt Yres Exact Online zonder per tabel handwerk?
Per tabel staat in de metadata welke kolommen hij heeft, welke sleutel en welke laadwijze. Eén pijplijn voor Exact Online doet voor elke tabel hetzelfde werk. Sanne kiest per tabel alleen de wijzigingskolom en of hij meeloopt.
Ik kan Exact toch rechtstreeks in Power BI koppelen?
Ja, voor de actuele cijfers van één administratie en één rapport werkt dat goed en is het sneller ingericht. Wel leest elke verversing van het rapport de API opnieuw, met dezelfde pagina's en hetzelfde budget. Zodra je historie of meerdere administraties wilt, laat je Power BI uit het datawarehouse lezen.
Wat gebeurt er als de token verloopt midden in de nacht?
Niets wat je merkt. Yres controleert het bewijs vóór elke tabel en vernieuwt het zelf. Mislukt een tabel toch, dan is het watermerk niet opgeschoven en haalt Yres die tabel de volgende nacht opnieuw op vanaf hetzelfde punt.
Hoe voorkom ik dat het eerste laden de daglimiet raakt?
Door het over een paar nachten te spreiden. Zet een deel van de tabellen tijdelijk uit en zet elke nacht een volgend deel aan. Begin met de tabellen die je het eerst nodig hebt.
Praat met een data-architect
In 30 minuten kijkt een data-architect met je mee naar je huidige dataomgeving en waar het nu wringt.
Plan een gesprek →
