FME server script als Onemap API koppeling
- wvandooremolen
Samenvatting
In Onemap kan , vanuit de featureinfo, additionele informatie worden opgehaald en getoond vanuit relevante REST API endpoints.
Het uitgangspunt hierbij is dat een laag in Onemap attributen bevat die gevoed kunnen worden aan het gekoppelde endpoint. bv:
Een laag met percelen (vanuit PDOK) bevat de attributen (perceel identificatie) om bij de haalcentraal-BRK endpoints extra informatie op te halen die niet als attribuut in de laag aanwezig is (bv: zakelijke rechten of eigenaren van een perceel)
De Rest interface bevat doorgaans meerdere endpoints die aan elkaar zijn gerelateerd. Op die manier kan worden doorgevraagd over meerdere Rest-endpoints. Om dit in Onemap te kunnen koppelen is het zaak om 1 start endpoint te configureren , en zelf de relevante gegevens hiervoor te verzamelen en terug te geven.
FME (desktop/server) is een generieke tool waarmee dit zou kunnen worden ingericht.
In deze workshop gaan we dit uitvoeren voor de Basis Registratie Ondergrond (BRO).
De beschikbare BRO Rest-endpoints zijn beschreven in BRO publieke Rest services
In PDOK zijn een aantal BRO lagen beschikbaar (sonderingen, booronderzoeken, grondwater meetpunten..).
Deze lagen bevatten de BRO identificatie attributen waarmee De BRO publieke Rest services kunnen worden bevraagd. Deze services bevatten o.a. endpoints om bijbehorende metingen en gegevens grafisch te presenteren (bv de bodem profielen).
In deze workshop gaan we deze grafische presentaties ophalen en toevoegen aan de Onemap feature informatie.
De algemene werkwijze hiervoor is als volgt:
Maak een FME script ( met FME desktop) dat gevoed wordt met attributen ( en waardes) die nodig zijn om de REST services te bevragen.
Verzamel de gewenste gegevens door ( vanuit het script) een aantal Rest endpoints sequentieel te bevragen. Lever de verzamelde gegevens aan in json formaat.
Upload het script naar FME Server, en maak hiervoor een ‘WebHook' aan. De 'WebHook’ kan vervolgens als API-endpoint worden gekoppeld in Onemap.
Richt het API basis endpoint in bij de Onemap workspace systeem instellingen.
Koppel dit basis endpoint aan de featureinfo van de bijbehorende laag.
Maak het FME Desktop script
Het benodigde FME script bevat doorgaans de volgende onderdelen:
De parameters die voor de Rest-services nodig zijn, en die als attribuut in de Onemap laag beschikbaar zijn.
Een 'creator' transformer om het proces te starten
Een ( of meerdere ) 'http_caller' transformers om de relevante Rest-endpoints te bevragen
Een JSON writer
De precieze invulling van het script is verder afhankelijk van hoe de Rest services zijn ingericht en communiceren.
Richt een FME server WebHook in
Upload FME script naar FME server
Registreer dit als een 'Data Streaming' service
Publiceer het script als een FME WebHook
Een FME Server Webhook vormt een API-endpoint dat met een api-key is geauthoriseerd.
Download de webhook configuratie instellingen en bewaar deze.
Configureer de API koppeling in Onemap
Allereerst wordt het basis endpoint toegevoegd bij de API-configuraties in de workspace systeem instellingen.
Het basis endpoint bevat de basis-URL ( alles tot het ? ) en een HTML header met de benodigde authorizatie.
Het tweede deel voor de API/WebHook aanroep wordt uitgevoerd in de laag/featureinfo configuratie. Hier hebben we (doorgaans) de benodigde parameters tot onze beschikking.
WMS services leveren niet altijd de bijbehorende veld definities (de functie 'DescribeFeature' is voor WMS niet verplicht).
De workarounds zijn dan:
1-Gebruik de bijbehorende WFS (waar ‘describefeature’ wel verplicht is)
Indien de WFS niet als service beschikbaar is:
2-Herleid de laag velden door in de WMS de featureinfo middels TWIG toch te implementeren en vervolgens op de kaart een keer uit te voeren. (e.a. is beschreven in Twig templates)
Helaas doet deze situatie zich voor bij de BRO-PDOK lagen. Door eenmalig een featureinfo in Onemap uit te voeren krijgen we zo toch de beschikking over de aanwezige attributen.
We kunnen nu de API/WebHook aanroep inrichten door de BRO_ID parameter in de aanroep toe te voegen.
De Rest-API’s leveren gegevens terug in json formaat. In Onemap moet deze json vervolgens geparsed worden naar een html formaat m.b.v. TWIG.
In dit geval wordt de grafiek in svg ( xml formaat) terug geleverd als waarde van het json item 'json_result'. Deze waarde kan direct worden opgenomen in de featureinfocode als waarde.
Omdat FME de json altijd als json-array teruggeeft moet eerst nog het eerste element naar een 'normale' json worden gezet.
De api koppeling die naast de featureinfo is ingericht komt , binnen de featureinfo, als tabblad/button beschikbaar. Door hier op te klikken wordt een request naar de fme server webhook verstuurd ( met het bijbehorende bro_id) en wordt ( in dit geval) het bodemprofiel grafisch teruggeleverd.
Opdracht:
1-Ontwikkel en implementeer met FME een API koppeling om de bodemprofielen als grafiek in de featureinfo te kunnen bekijken.
Iedere REST interface vraagt kennis over de opbouw en de inhoud die de Rest services leveren. Meestal worden de Rest services in een vorm gepresenteerd (bv swagger UI) waarmee de gebruiker individuele endpoints kan testen.
We gaan eerst de te nemen stappen uitvoeren op de swagger_UI van de BRO rest interface.
Vervolgens gaan we deze stappen geautomatiseerd opnemen in een FME script.
Bekijk de REST services op BRO Rest services, we zien hier dat er twee sets van endpoints worden gegeven:
uitgifte
visualisatie
We pakken eerst de BHRP uitgifte service.
BHR-P uitgifte en validatie
url: https://publiek.broservices.nl/sr/bhrp/v2
Als we deze openen en vervolgens de documentatie link openen komen we uit op de swagger UI van deze rest services.
Hier zien we een endpoint om gegevens van een individueel boorpunt op te halen.
/sr/bhrp/v2/objects/{broId}
Als je deze openklikt en kiest voor 'tryout' kun je kijken wat dit endpoint terug levert. Probeer dit voor het volgende boorpunt ID: bro_id: BHR000000350843
Vul het broid in en klik op 'execute'
Je ziet vervolgens hoe de vraag wordt afgevuurd (request url). Bij een correcte verwerking krijg je een responsecode 200 en het antwoord.
Kopieer dit antwoord naar het clipboard
We gaan nu naar de bijbehorende visualisatie Rest services:
Hier zien we o.a. het volgende endpoint:
/sr/sfr/v2/profile/graph/dispatch
met als omschrijving: Grafische weergave boorprofiel op basis van een uitgifteresultaat (laag, diepte, kleur).
Ga ook deze middels 'tryout testen.
We hebben hier een veld 'request body' waarvan we de inhoud kunnen vervangen door het zojuist gekopieerde antwoord van het uitgifte-endpoint.
Als we deze uitvoeren zien we weer de uitgevoerde request en het antwoord. In het antwoord zien we dat er een xml wordt terggegeven en dat deze een SVG item bevat.
Deze svg zal in een html pagina worden getoond als de bodemprofiel grafiek.
We hebben het ophalen van een bodemprofiel grafiek voor een boorpunt nu uitgevoerd op de swagger-UI endpoints van de BRO rest services.
Probeer deze stappen nu op te nemen in een FME script:
1-defineer een user parameter voor de bro id
2-gebruik een http_caller om de uitgifte gegevens op te halen ( uitgifte GET met een bro_id als parameter)
3-gebruik een http_caller om het uitgifte resultaat als SVG grafiek op te halen (visualisatie POST met response uit eerste call als body)
4-plaats het resultaat van de SVG call in een json writer
opm: xml header uit de SVG response moet nog worden verwijdert. Dit kan bv met:
Maak zelf een attribuut aan in de json writer waarin het SVG resultaat wordt geplaatst.
Als het script goed werkt kan het naar FME server worden gebracht om als 'convienient API' te worden gebruikt voor Onemap.
2-Uploaden naar FMEServer en inrichten als webhoook
Upload het script naar fme server. Dit kan via de publish knop in de menubar.
Gebruik de reeds aanwezige connectie (meteen naar next)
Selecteer de repositry 'workshop', en geef de fme script de prefix die overeenkomt met de workshop kaart waarin je aan het werk gaat ( bv: BRO_boring_workshop_1)
Registreer de service als een 'Data Streaming' service en publiceer:
We gaan nu op FMEServer het FME script inrichten als een 'FME Webhook'. Deze webhook kan daarna in Onemap worden opgenomen en worden ingericht om het antwoord van het fme script vanuit dee object-featureinfo op te halen.
Open workshop fmeserver en login met:
gebruiker=workshop
paswoord=pohskrow
Selecteer repository=workshop en workspace= 'jouw script'
Kies vervolgens onder ‘workspace actions' voor 'create webhook’
Een FME Server Webhook vormt een API-endpoint dat met een api-key is geauthoriseerd.
Download de webhook configuratie instellingen en bewaar deze.
Configureer de API koppeling in Onemap
Log in op de workshop workspace
Er zijn 5 kaartbeheerders en 5 beschikbare kaarten. Je krijgt hiervoor een nummer toegewezen.
gebruiker = workshop_FME_1
paswoord = workshop_FME_1
Allereerst wordt het basis endpoint toegevoegd bij de API-configuraties in de workspace systeem instellingen.
Het basis endpoint bevat de basis-URL ( alles tot het ? ) en een HTML header met de benodigde authorizatie.
Open nu de aan jouw toegewezen workshop kaart (bv FME workshop 1)
We kunnen nu de API/WebHook aanroep inrichten door de BRO_ID parameter in de aanroep toe te voegen.
1-Kies de zojuist ingerichte api-koppeling en breid deze uit met de benodigde parameter waarde van het aangeklikte feature.
2-Voeg ( in broncode modus) de twig statements toe om de json inhoud te visualiseren.