Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 12 Next »

De API kan gebruikt worden in combinatie met een script omgeving. Hier zijn een aantal voorbeelden opgenomen die zijn gemaakt met een Python (Jupyter lab) omgeving. In het voorbeeld worden alle stappen van de API toegelicht. Basiskennis van het gebruik van Python is verondersteld.

Informatie van de API opvragen

U kunt informatie van de API opvragen zonder in te loggen. In onderstaand voorbeeld definieren we eerst het gebruik van de module ‘requests' (zie ook deze documentatie), zodat we de HyDAMO validatie-API in Python kunnen gebruiken. Ook definieren we het gebruik van de module 'os' zodat we later eenvoudig bestanden en paden kunnen samenvoegen (met het commando os.path.join). Vervolgens geven we de URL van de server met de HyDAMO validatie-API op. Omdat de webservice gebruikt maakt van een (HTTPS) beveiligingscertificaat moeten we deze ook meegeven (@@@@ locatie git @@@@). Daarna voeren we het GET request uit voor het verkrijgen van de informatie en slaan we het resultaat op in de variabele 'response’. Als de HTML statuscode van de response gelijk is aan 200 (de API geeft succesvol een resultaat van onze request), dan schrijven we het resultaat van de response naar het scherm. In Python code ziet dat er als volgt uit:

import requests
import os

server = "https://validatie-api.hydamo.nl"
hydamo_cert = r"...\HyDAMOValidatietool.pem"

#https://validatie-api.hydamo.nl/
response = requests.get(f"{server}/", verify=verify)

if response.status_code == 200:
  print(response.text)

Het resultaat is:

{"version":"0.9.1","validation_module":"0.9.3","title":"HyDAMO Validationtool","description": "HyDAMO Validationtool","contact":"helpdesk-hydamo-validatietool@hkv.nl"}

Inloggen

Om gebruik te kunnen maken van de HyDAMO Validatiemodule en de validatie-API moet u geauthentiseerd worden. Hiertoe kunt u een gebruikersnaam en wachtwoord opvragen (zie Gebruikersregistratie). Heeft u de beschikking over en gebruikersnaam en wachtwoord, dan kunt u zich authentiseren met de API. De API maakt gebruik van OAuth Firebase Authentication. Dit betekent dat u zich authentiseert bij een server van Google. Daartoe maakt u gebruik van een standaard API van Google. Om kenbaar te maken dat u zich wilt authentiseren voor de HyDAMO Validatietool, gebruikt u een specifieke key (AIzaSyAU17otJko594SYoCulCPfXwkHOXQEieXE). Vervolgens stelt u een Python dictionary samen met uw gebruikersnaam (label dit als ‘email’) en uw wachtwoord (label dit als 'password'). Daarna maakt u een POST request naar de Google API, waarbij u de dictionary met uw cedentials meestuurt. Als de HTML statuscode van de response gelijk is aan 200 (de Google API geeft succesvol een resultaat), dan bevat de response een zogenaamde id_token. Deze wordt omgezet in een Bearer token (een gecodeerde token) die daarna als header meegeven kan worden aan toekomstige requests aan de HyDAMO validatie-API en waarmee u wordt geauthentiseerd. In Python ziet de code er als volgt uit (gebruikersnaam en wachtwoord zijn fictief in het voorbeeld):

username = "gebruiker@hydamo.nl"
password = "*****"

firebase_url = "https://identitytoolkit.googleapis.com/v1"
firebase_key = "AIzaSyAU17otJko594SYoCulCPfXwkHOXQEieXE"

response = requests.post(f"{firebase_url}/accounts:signInWithPassword?key={firebase_key}", data={'email': username, 'password': password, 'returnSecureToken': 'true'})

if response.status_code == 200:
  id_token = response.json()['idToken']
  my_headers = {'Authorization': f"Bearer {id_token}"}   
  print(my_headers)

Het resultaat is (de daadwerkelijke Bearer token is vervangen door sterretjes):

{'Authorization': 'Bearer **********************************************************************'}

Een nieuwe validatie-taak aanmaken

U kunt via de HyDAMO validatie-API en nieuwe validatie-taak aanmaken. Hiertoe moet u beschikken over een uniek Bearer token, zodat u geauthentiseerd kunt worden. Voor een nieuwe validatie-taak moet u een willekeurige naam definieren. Met een POST request naar de API op het endpoint van tasks kunt u een nieuwe taak aanmaken. U geeft hierbij de naam van de taak mee, de Bearer token (opgeslagen in my_headers) en het (HTTPS) beveiligingscertificaat (verify=hydamo_cert). Als de HTML statuscode van de response gelijk is aan 201 (het post request geeft aan dat de aanpassing succesvol is doorgevoerd), kunnen verschillende gegevens (data) van de validatie-taak uit de response uitgelezen worden, waaronder:

  • de unieke id die de online (reken)omgeving heeft toegewezen aan uw validatie-taak

  • de naam die uw zelf heeft meegegeven aan de nieuwe validatie-taak

  • de status van de nieuwe validatie-taak (altijd gelijk aan 'new')

  • het aantal dataset bestanden dat is toegevoegd aan de validatie-taak

  • en of de validatie-taak validatieregels bevat.

task_name = "Voorbeeld_Wiki"

#https://validatie-api.hydamo.nl/tasks/Voorbeeld_Wiki
response_new_task= requests.post(f"{server}/tasks/{task_name}", headers=my_headers, verify=hydamo_cert)

if response_new_task.status_code == 201:
  data = response_new_task.json()
  print("id: " + str(data["id"]))
  print("naam: " + str(data["name"]))
  print("status: " + str(data["status"]))
  print("aantal dataset bestanden: " + str(data["numberOfDatasets"]))
  print("validatieregels aanwezig: " + str(data["validationRules"]))

Het resultaat is:

id: 1495 (dit id is een voorbeeld)
naam: Voorbeeld_Wiki
status: new
aantal dataset bestanden: 0
validatieregels aanwezig: False

Een dataset toevoegen aan de validatie-taak

Als er een validatie-taak beschikbaar is, kunt u 1 of meerdere dataset bestanden toevoegen aan deze validatie-taak. Hiertoe moet eerst een verwijzing naar 1 of meerdere databestanden gemaakt. Een databestand kan meerdere objectlagen bevatten of een databestand bevat 1 enkele objectlaag. In het laatste geval kunt u ook meerdere databestanden (tegelijk) toevoegen aan een validatie-taak. De dataset bestanden:

  • moeten voldoen aan het DAMO 2.2. datamodel. Zie voor meer informatie DAMO 2.2 Objectenboek.

  • de data is van het (open data) formaat Geopackage (extensie *.gpkg). Zie voor meer informatie Geopackage.

In het voorbeeld zijn meerdere databestanden (met duikersifonhevels, hydro-objecten en regelmiddelen) in een array (tabel) datasets opgenomen. De dataset bestanden zelf staan in een folder op het computersysteem waar naar verwezen kan worden (file_path). Om de datasets te kunnen toevoegen aan de validatie-taak, is de taak-id nodig van de, in de vorige stap nieuw aangemaakte taak. Deze kan uit de response van de API call, waamee de nieuwe taak is aangemaakt, gehaald worden (attribuut: id). In een lus kunt u de verschillende databestanden 1 voor 1 toe voegen. Voor elke dataset maakt u eerst een dictionary params aan. Hierin wordt de naam van het databestand opgeslagen (aan het label ‘file’). Daarna maakt u ook een dictionary files aan. Hierin wordt het databestand zelf opgeslagen (via een commando ‘open' en het attribuut 'rb’; de dataset wordt als een binair bestand opgeslagen). Met een POST request naar de API op het endpoint van task/datasets kunt u een databestand toevoegen aan de validatie-taak. U geeft hierbij de id van de validatie-taak mee (in de URL) en de dictionaries files en params, de Bearer token (opgeslagen in my_headers) en het (HTTPS) beveiligingscertificaat (verify=hydamo_cert). Als de HTML statuscode van de response gelijk is aan 201 (het post request geeft aan dat de aanpassing succesvol is doorgevoerd), kunnen verschillende gegevens (data) van de validatie-taak uit de response uitgelezen worden, waaronder:

  • de unieke id van uw validatie-taak

  • en het aantal dataset bestanden dat is toegevoegd aan de validatie-taak.

De lus eindigt na het wegschrijven van de resultaten (id en het aantal dataset bestanden toegevoegd aan uw taak).

file_path = r"...\ValidatietoolHyDAMO\Wiki\Datasetbestanden"
datasets = ["DuikerSifonHevel.gpkg", "HydroObject.gpkg", "Regelmiddel.gpkg"]
task_id = response_new_task.json()["id"]

for dataset in datasets:
  params = {"file": dataset}
  files = {"file": open(os.path.join(file_path,dataset), "rb")}
  
  #https://validatie-api.hydamo.nl/task/[task_id]/datasets
  response_upload_datasets = requests.post(f"{server}/task/{task_id}/datasets", files=files, params=params, headers=my_headers, verify=hydamo_cert) 
  if response_upload_datasets.status_code == 201:
    data = response_upload_datasets.json()
    print("id: " + str(data["id"]))
    print("naam dataset: " + dataset)
    print("aantal dataset bestanden: " + str(data["numberOfDatasets"]))

Het resultaat is:

id: 1495 (dit id is een voorbeeld)
naam dataset: DuikerSifonHevel.gpkg
aantal dataset bestanden: 1
id: 1495 (dit id is een voorbeeld)
naam dataset: HydroObject.gpkg
aantal dataset bestanden: 2
id: 1495 (dit id is een voorbeeld)
naam dataset: Regelmiddel.gpkg
aantal dataset bestanden: 3

Een bestand met validatieregels toevoegen aan de validatie-taak

Als er een validatie-taak beschikbaar is, kunt u bestand met validatieregels toevoegen aan deze validatie-taak. Meer informatie over de inhoud van het bestand met validatieregels vindt u hier (@@link@@).

Het bestand met validatieregels staat in een folder op het computersysteem waar naar verwezen kan worden (file_path). We maken gebruik van een versie van het bestand met alle validatieregels (zie hier voor de laatste versie). Om validatieregels te kunnen toevoegen aan de validatie-taak, is de taak-id nodig van de validatie-taak (zie voorgaande stappen). U maakt vervolgens eerst een dictionary params aan. Hierin wordt de naam van het bestand met validatieregels opgeslagen (aan het label ‘file’). Daarna maakt u ook een dictionary files aan. Hierin wordt het bestand met validatieregels zelf opgeslagen (via een commando ‘open' en het attribuut 'rb’; het bestand met validatieregels wordt als een binair bestand opgeslagen). Met een POST request naar de API op het endpoint van task/validationrules kunt u een bestand met validatieregels toevoegen aan de validatie-taak. U geeft hierbij de id van de validatie-taak mee (in de URL) en de dictionaries files en params, de Bearer token (opgeslagen in my_headers) en het (HTTPS) beveiligingscertificaat (verify=hydamo_cert). Als de HTML statuscode van de response gelijk is aan 201 (het post request geeft aan dat de aanpassing succesvol is doorgevoerd), kunnen verschillende gegevens (data) van de validatie-taak uit de response uitgelezen worden, waaronder:

  • de unieke id van uw validatie-taak

  • en of de validatie-taak validatieregels bevat.

file_path = r"...ValidatietoolHyDAMO\Wiki\Validatieregels"
validationrules = "validationrules_complete.json"

params = {"file": validationrules}
files = {"file": open(os.path.join(file_path,validationrules), "rb")}

#http://validatie-api.hydamo.nl/task/[task_id]/validationrules
response_upload_validationrules = requests.post(f"{server}/task/{task_id}/validationrules", files=files, params=params, headers=my_headers, verify=hydamo_cert) 

if response_upload_validationrules.status_code == 201:
    data = response_upload_validationrules.json()
    print("id: " + str(data["id"]))
    print("validatieregels aanwezig: " + str(data["validationRules"]))

Het resultaat is:

id: 1495 (dit id is een voorbeeld)
validatieregels aanwezig: True

Controleer de status van een validatie-taak

Voordat een validatie-taak gestart kan worden moet aan een taak minimaal 1 dataset bestand en een bestand met validatieregels zijn toegevoegd. U kunt aan de hand van de status van een validatie-taak controleren of een validatie-taak gereed is voor validatie. De status is dan gelijk aan ready_to_validate.

U kunt de status van een validatie-taak op elk moment opvragen met een GET request naar de API op het endpoint van task, waarbij u de validatie-taak id (in de URL), de Bearer token (opgeslagen in my_headers) en het (HTTPS) beveiligingscertificaat (verify=hydamo_cert) meegeeft. ls de HTML statuscode van de response gelijk is aan 200 (het post request geeft aan dat de informayie succesvol is opgehaald), kunnen verschillende gegevens (data) van de validatie-taak uit de response uitgelezen worden, waaronder de status van de validatie-taak.

#http://validatie-api.hydamo.nl/task/[task_id]/
response_get_task = requests.get(f"{server}/task/{task_id}", headers=my_headers, verify=hydamo_cert) 

if response_get_task.status_code == 200:
    data = response_get_task.json()
    print(str(data["status"]))

Het resultaat is:

status: ready_to_validate

Start een validatie-taak

Tekst TODO

Geef formaat van bestanden die je als resultaat wilt (CSV, geopackage of geojson, of een combinatie van voorgaande)

Na het starten de status controleren!

#http://validatie-api.hydamo.nl/task/[task_id]/execute/csv,geopackage,geojson
format = "csv,geopackage,geojson"

response_execute_task = requests.post(f"{server}/task/{task_id}/execute/{format}", headers=my_headers, verify=hydamo_cert) 

if response_execute_task.status_code == 202:
    print('Taak is gestart!')

Het resultaat is:

TODO

Download metadata van de validatie-taak

Tekst TODO

Als een taak gereed is, download metadata ter controle van resultaat.

Definieer een map waar de resultaat bestanden opgeslagen moeten worden.

#http://validatie-api.hydamo.nl/task/[task_id]/result/metadata
result_folder = r"...\Resultaten"

response_get_metadata = requests.get(server + '/task/' + str(task_id) + '/result/metadata', headers=my_headers, verify=hydamo_cert)

if response_get_metadata.status_code == 200:
    result_data = bytes(response_get_metadata.content)
    if not os.path.exists(result_folder):
        os.makedirs(result_folder)
    open(os.path.join(result_folder,f"{task_id}_metadata.json"), 'wb').write(response_get_metadata.content)

Het resultaat is:

TODO

Download resulaten van de validatie-taak in CSV

Tekst TODO

Als een taak gereed is, download het resultaat als CSV per objectlaag (bijv stuw).

#http://validatie-api.hydamo.nl/task/[task_id]/result/[objectlaag].csv

response_get_results_csv = requests.get(server + '/task/' + str(task_id) + '/result/stuw.csv', headers=my_headers, verify=hydamo_cert)
                                
if response_get_results_csv.status_code == 200:
    result_data = bytes(response_get_results_csv.content)
    if not os.path.exists(result_folder):
        os.makedirs(result_folder)
    open(os.path.join(result_folder,"stuw.csv"), 'wb').write(response_get_results_csv.content)

Het resultaat is:

TODO

Een validatie-taak annuleren

Tekst TODO

#http://validatie-api.hydamo.nl/task/[task_id]/kill

response_get_results_csv = requests.get(server + '/task/' + str(task_id) + '/kill', headers=my_headers, verify=hydamo_cert)
                                
if response_get_results_csv.status_code == 201:
    print('Taak is geannuleerd!')

Het resultaat is:

TODO

  • No labels