Data up-to-date houden

Het Opendatasoft-platform maakt het mogelijk om, in precies dezelfde datacatalogus, statische datasets (die slechts één keer moeten worden gepubliceerd) en live datasets (die regelmatig up-to-date moeten worden gebracht), volledig te behandelen. Er worden twee verschillende mechanismen beschikbaar gesteld om het hernieuwen van datasets uit te voeren.

Het eerste wordt planning genoemd en bestaat erin dat een dataset met vaste tussenpozen automatisch opnieuw wordt gepubliceerd. Dit mechanisme is nuttig voor datasets met een bron op afstand die regelmatig up-to-date wordt gebracht.

Het tweede mechanisme bestaat eruit dat data op het Opendatasoft-platform wordt gepusht door gebruik te maken van een speciaal API-eindpunt. Dit mechanisme is het nuttigst wanneer de data rechtstreeks door het systeem worden gestuurd dat de datapunten produceert, zoals een computerprogramma dat cijfers van een evenement doorstuurt of een reeks sensoren die hun afleesresultaten doorsturen.

Planning gebruiken om een dataset up-to-date te houden

Opgelet

De beschikbaarheid van deze functionaliteit hangt af van de licentie van het Opendatasoft-domein.

Deze oplossing is het gemakkelijkst om te implementeren. Ze vereist geen enkele ontwikkeling, enkel een bron op afstand en enkele instellingen in de datasetconfiguratie.

Een bron specificeren

../../_images/scheduling_source-url.png

Om een dataset te kunnen plannen, moet de onderliggende bron ervan een op afstand zijn, gespecificeerd als een URL (http of ftp werken goed) en geen geüpload bestand. Om een dergelijke bron toe te voegen, dient u de URL enkel te plakken in de URL input.

Planningsinterval specificeren

../../_images/scheduling_tab.png

Eenmaal de dataset is opgeslagen met een bron op afstand, wordt het planningstabblad geactiveerd. De minimale interval is een minuut, maar deze wordt niet standaard geactiveerd. Gelieve contact op te nemen met het Support Team van Opendatasoft wanneer u een planningsniveau van één minuut op uw domein nodig hebt. Wanneer dit beantwoordt aan uw noden, zou u kunnen beslissen om een dataset zodanig te plannen dat deze elke maandagmorgen en elke woensdagnamiddag opnieuw wordt verwerkt.

Real time data pushen

Opgelet

De beschikbaarheid van deze functionaliteit hangt af van de licentie van het Opendatasoft-domein.

Voor sommige types data kan het nuttig zijn om data te pushen in plaats van het meer traditionele model te gebruiken waarbij de data door het platform wordt weggehaald uit een bron. Om aan deze behoefte te beantwoorden, biedt het Opendatasoft-platform een real time push-API. Deze mag niet verward worden met de mogelijkheid om de verwerking van een dataset te plannen. Wanneer gepland wordt, zal de dataset op periodieke basis de bron weghalen en de data die erin staan verwerken, terwijl met de push-API de dataset gevoed wordt door een applicatie via een push-API en records één voor één worden verwerkt zodra ze worden ontvangen.

Het datasetschema configureren

../../_images/realtime_source.png

Om een real time dataset aan te maken, ga naar de aanmaakinterface van de dataset. Selecteer hier "voeg een real time bron toe".

realtime resource pane

Er zal u worden gevraagd om enkele bootstrap-gegevens in te voeren en om optioneel extra opties in te vullen. De bootstrap-gegevens zouden alle velden moeten hebben die via de API worden gestuurd. Gelieve te noteren dat de bootstrap-gegevens niet gebruikt worden in de dataset: ze hebben enkel als doel het mogelijk te maken de dataset op te zetten.

De push-URL gebruiken

../../_images/realtime_pushurl.png

Eenmaal uw dataset is opgeslagen met de juiste real time broninstellingen, verschijnt er een URL-pad dat een push API-sleutel bevat. Dit pad, dat aan de basis-URL van uw domein wordt gekoppeld, is waar verwacht wordt dat het platform data naar toe zal sturen na publicatie. Net zoals bij bootstrap-gegevens, wordt verwacht dat de data verstuurd wordt in JSON-formaat, ofwel als een enkel JSON-voorwerp voor een enkel record of een array van JSON-voorwerpen om meerdere records in één keer te pushen.

table view with a single record with value "Hello World!" in the "message" field

Een minimaal voorbeeld van het gebruik van de API voor een dataset met een enkel veld met de naam "bericht", waarbij een URL wordt gebruikt, zou zijn

curl -XPOST <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/push/?pushkey=<PUSH_API_KEY> -d'{"message":"Hello World!"}'

Een minimaal voorbeeld met dezelfde dataset, waarbij het array-formulier om meerdere records in één keer te versturen, wordt gebruikt, zou zijn

curl -XPOST <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/push/?pushkey=<PUSH_API_KEY> -d'[{"message":"¡Hola Mundo!"},{"message":"Hallo Welt!"}]'

Wanneer de records correct ontvangen werden, zal de server het volgende bericht sturen.

{
    "status": "OK"
}

Wanneer er een fout is opgetreden tijdens het proberen pushen van een record, zal in het antwoord de fout gespecificeerd worden.

Opmerking

Real time push-verzoeken zijn beperkt tot een payload van 5MB. Een grotere payload zal aanleiding geven tot een fout en dient in plaats daarvan te worden opgesplitst in verschillende kleinere verzoeken.

Een veld van een type bestand pushen

Om een veld van het type afbeelding te pushen, moet een JSON-voorwerp dat de base64-encoded content en het mimetype van het bestand als dusdanig worden opgestuurd.

{
    "image_field": {
        "content": "BASE64 data",
        "content-type": "image/jpg"
    }
}

Data updaten door het definiëren van een unieke sleutel

table view with 2 records containing respectively 978-0060589462 and 978-2862744506 as isbn and 3 and 5 as number_of_copies

Soms is het nuttig om de bestaande records te updaten in plaats van gewoon nieuwe te pushen. Een voorbeeld hiervan zou zijn: een dataset die het aantal kopieën opvolgt dat voor elk boek beschikbaar is in een openbare bibliotheek. Veronderstel dat we een dergelijke dataset hebben met twee velden: isbn, dat het ISBN nummer van het boek vertegenwoordigt, en number_of_copies dat het huidige aantal kopieën dat beschikbaar is in de bibliotheek opvolgt. Het zou niet echt zinvol zijn om één record voor elke nieuwe waarde van number_of_copies toe te voegen. In plaats daarvan zou het beter zijn om de nieuwe number_of_copies waarde in te stellen voor het record dat overeenstemt met de isbn van het boek.

../../_images/realtime_unique-id.png

Om een dergelijk systeem binnen het Opendatasoft-platform op te zetten, moeten de velden die als unieke sleutel gebruikt zullen worden, als dusdanig gemarkeerd moeten worden. In ons voorbeeld zou de unieke sleutel isbn zijn, omdat de rest van de data gekoppeld is aan individuele boeken en deze boeken worden geïdentificeerd op basis van de ISBN. Dit kan gedaan worden in de verwerkingsweergave, in het menu dat tevoorschijn komt wanneer op de configuratieknop wordt geklikt. Het is mogelijk om meerdere velden in te stellen als unieke sleutels. Vervolgens, na het opslaan en publiceren, wanneer een nieuw record waarvan de sleutelwaarde gelijk is aan een bestaand record, wordt gepusht, zal het nieuwe record het oude record overschrijven. In het geval van onze bibliotheek, wanneer uw dataset isbn als unieke sleutel heeft, en deze twee records bevat.

[
    {
        "isbn": "978-0060589462",
        "number_of_copies": 3
    }, {
        "isbn": "978-2862744506",
        "number_of_copies": 5
    }
]

Wanneer iemand een kopie van Zen en the Art of Motorcyle Maintenance leent en u het volgende record pusht, zal u nog steeds twee records hebben, waarbij het eerste up-to-date wordt gebracht met de nieuwe waarde.

{
    "isbn": "978-0060589462",
    "number_of_copies": 2
}
table view with 2 records containing respectively 978-0060589462 and 978-2862744506 as isbn and 2 and 5 as number_of_copies

Data verwijderen

Er zijn twee entrypoints die het mogelijk maken om gepushte records te verwijderen. Eén dat de waarden van records gebruikt en één dat het record-ID gebruikt.

De recordwaarden gebruiken

Om een record, waarvan u de waarden van de recordvelden kent, te verwijderen, POST het record alsof u dit voor de eerste keer zou toevoegen, maar vervang /push/ door /delete/ in de push URL. Wanneer uw push URL-pad /api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/push/?pushkey=<PUSH_API_KEY> is, gebruik dan in plaats daarvan /api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/delete/?pushkey=<PUSH_API_KEY>. Een minimaal voorbeeld om het record dat we eerder hebben gepusht, te verwijderen, volgt.

curl -XPOST <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/delete/?pushkey=<PUSH_API_KEY> -d'{"message":"Hello World!"}'

Het record-ID gebruiken

Wanneer u het record-ID van het record dat u wil verwijderen, kent, doe dan gewoon een GET-aanvraag aan de URL die u krijgt door /push/ te vervangen door /<RECORD_ID>/delete/ in de push URL. Een minimaal voorbeeld hiervan volgt.

curl -XGET <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/<RECORD_ID>/delete/?pushkey=<PUSH_API_KEY>

Krijg een bericht in geval van inactiviteit

../../_images/realtime_alerting.png

Wanneer u verwacht dat een systeem vaak data naar het platform zal pushen, is het mogelijk dat u hiervan in kennis wordt gesteld wanneer er al een tijdje geen record werd ontvangen door het platform. Om in kennis gesteld te worden, kan u de optie "Waarschuwing" activeren in de bronconfiguratie en een tijddrempel instellen in minuten. Wanneer een periode verstreken is die langer is dan de drempel en waarin geen enkel record werd ontvangen, ontvangt u een e-mail.

De publicatie van de API ongedaan maken en deze deactiveren

../../_images/realtime_disable-button.png

Opgelet wanneer u de publicatie van uw dataset ongedaan maakt, aangezien hierdoor bestaande records niet worden bijgehouden voor de volgende keer dat de dataset wordt gepubliceerd. Wanneer u wil vermijden dat u nieuwe data krijgt, dient u in plaats daarvan te klikken op "push deactiveren" in de broninstelling. Hiermee wordt voorkomen dat de push API wordt gebruikt, maar dit zal geen impact hebben op bestaande data. Wanneer data worden gepusht terwijl push gedeactiveerd is op de bron, zullen geen data worden toegevoegd en zal er een fout worden gestuurd.

Recuperatie

../../_images/realtime_recovery.png

In geval van verlies van data, bijvoorbeeld wanneer de publicatie van de dataset ongedaan werd gemaakt of wanneer een processor verkeerd werd geconfigureerd, is er een mogelijkheid om de verloren gegane records te recupereren. Hiervoor moet de recuperatie-optie geactiveerd zijn vóór de records naar het platform werden gepusht.

../../_images/realtime_recovery-button.png

Wanneer de recuperatie is geactiveerd zal van elk daarop volgend record dat ontvangen wordt een back-up worden gemaakt en deze zal in aanmerking komen om te worden gerecupereerd. Om records te recupereren die in aanmerking komen, kan de knop "recupereer data" op de configuratiepagina van de bron gebruikt worden.