Skip to end of metadata
Go to start of metadata

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

Compare with Current View Version History

« Previous Version 2 Next »

Moeilijkheidsgraad: expert

Inhoud

Leerdoelen

Na het lezen van dit artikel zul je in staat zijn om:

  • begrijpen wat API's voor Workplace kunnen doen

  • workplace API's testen

API staat voor Application Programming Interface en maakt eenvoudige uitwisseling van gegevens en functionaliteit mogelijk. De Workplace API documentatie (Swagger) is beschikbaar in een apart tabblad in het GO menu.

Hoe krijg ik toegang tot de API van Workplace?

De optie verschijnt alleen voor gebruikers met een ontwikkelaars- of beheerdersrol. Zie Roles & Profiles voor meer informatie.

Om de API's in je eigen projecten te gebruiken (bijvoorbeeld postman), is het misschien interessant om de swagger.json-link te gebruiken. Zoals je in de schermafbeelding kunt zien, wordt de "nieuwste" pagina standaard geopend, maar dit kan natuurlijk veranderen.

Gebruik genummerde versies (bijv. https://go.cobundu.com/rest/v3/docs) om conflicten te vermijden.

Het gebruik van een specifieke versie heeft het voordeel dat je in de toekomst API-versies kunt vergelijken.

De API testen: voorbeelden

Het is mogelijk om de API van Workplace uit te proberen/te testen. Afhankelijk van het verzoek moet je misschien eerst wat informatie invullen.

Voorbeeld 1. De lijst met sensorapparaten ophalen

  1. Selecteer "Uitproberen",

  2. en vervolgens "Uitvoeren",

  3. om een lijst te krijgen van alle sensorapparaten die momenteel aan deze huurder zijn gekoppeld.

Zoals je in het voorbeeld kunt zien, wordt elk sensorkanaal (bv. vochtigheid, temperatuur en CO2 in een comfortsensor) afzonderlijk geleverd.

Voorbeeld 2. De huidige sensorgegevens voor een locatie ophalen

  1. Selecteer "Uitproberen",

  2. Voeg de verplichte locatie-ID toe

  3. en vervolgens "Uitvoeren",

  4. om de huidige sensorgegevens op te halen van alle sensoren die gekoppeld zijn aan die locatie.

Zoals je in het voorbeeld kunt zien, is er 1 comfortsensor gekoppeld aan de opgevraagde locatie. Daarom worden alle beschikbare kanaalwaarden voor deze sensor (temperatuur en vochtigheid in dit geval) geleverd, evenals de tijdstempel waarvoor deze waarden werden ontvangen.

In de onderstaande voorbeelden wordt "locatie-ID" genoemd. Een locatie selecteren op https://go.cobundu.com/ wordt de referentie weergegeven, bijvoorbeeld "Vergaderzaal 1". Maar in de back-end van Workplace heeft elke locatie een unieke locatie-ID.

Locatie-ID is beschikbaar in de back-end van Workplace https://studio.cobundu.com URL voor elke geselecteerde locatie.

Bijvoorbeeld de Locatie ID voor verdieping "2e verdieping" in Spacewell Antwerpen is "910000000004545".

Voorbeeld 3. Reserveringen

Om de reserveringen uit je omgeving op te halen, kun je Reservations API > "een lijst met reserveringen ophalen" gebruiken.
Wijzig de datums in de zoekinstructie om (gefilterde) reserveringen te krijgen, elk met de locatie-ID, om zo aan te geven welke locatie is geboekt.
Voer locatie-id's in het zoekfilter in om gefilterde gegevens te krijgen.

Voorbeeld 4. Locatie-informatie opvragen

Een locatie selecteren op https://go.cobundu.com/ wordt de referentie weergegeven, bijvoorbeeld "Vergaderzaal 1". Maar in de back-end van Workplace heeft elke locatie een unieke locatie-ID.


Locations API kan je helpen die informatie te krijgen.
Afhankelijk van wat er nodig is:

  • een lijst met locaties krijgen voor deze klant

  • specifieke locatie-informatie opvragen (bijvoorbeeld informatie over een reeks "workplace"): "get location tree" (filter top-level resultaten = workplace)

Voorbeeld 5. Plattegrond

Om een plattegrond van de workplace te krijgen, selecteer je API Locations > "get a location's drawing as SVG".
De gevraagde locatie-ID is in dit geval de verdiepings-ID.
"Testen" in swagger geeft een antwoord, maar kan de SVG niet weergeven.

Voer de vloerlocatie-ID in de volgende URL in om de SVG te zien: https://go.eu1.cloud.cobundu.com/rest/latest/locations/vloer locatie ID/tekeningen/svg

Concrete use case: URL om live plattegrond te tonen

Stel je voor dat je een URL naar je kioskschermen wilt pushen om live gegevens van de Workplace plattegrond te visualiseren.

Hier stellen we voor om een toegangstoken met een URL op te geven, zodat iedereen met de link de live plattegrond kan zien.

Alternatieve methoden en veelgestelde vragen hierover vind je hier: Workplace live floorplan data visualization

De hieronder voorgestelde speciale methode omvat webauthenticatie via Rest API. Dit betekent dat een workplace login + wachtwoord nodig zijn, en de API retourneert een JWT token dat kan worden gebruikt om toegang te krijgen tot alle andere API-aanroepen.

Vereisten

  • Webkiosk moet worden geconfigureerd in Studio

  • Per verdieping waarvoor je visualisatie wilt instellen, is een Workplace gebruiker nodig:

    • Minimale rechten op de workplace/geen specifieke rol nodig

    • rekening houdend met reserveringsfuncties die zijn ingesteld voor deze omgeving

    • Gebruikersnaam + wachtwoord

  • Om toegang te krijgen tot API: Workplace gebruiker met een Admin of Developer rol

Oplossing

  1. API gebruiken om sessietoken te krijgen

    1. Ga naar http://go.cobundu.com (gebruiker heeft een beheerders- of ontwikkelaarsrol nodig) > API

      1. Selecteer "auth" > /rest/latest/auth/ssosettings/{loginId} (retourneer sso-instellingen voor de gebruiker)

      2. Geef gebruikersnaam

      3. De respons geeft de hostnaam van de cobundu SSO-instantie die moet worden gebruikt (Workplace IoT Platform is beschikbaar voor de EU en de VS) (kan bijvoorbeeld "apiUrl" zijn: https://go.eu1.cloud.cobundu.com )

    2. Nog steeds op http://go.cobundu.com (gebruiker heeft een beheerders- of ontwikkelaarsrol nodig) > API

      1. Selecteer "auth" > /rest/latest/login (gebruiker authenticeren)

      2. Geef de gebruikersnaam + het wachtwoord op dat wordt gebruikt om toegang te krijgen tot live gegevens

      3. Wijzig de aanmeldingsparameters "rememberme": true, "setCookie": true

      4. De respons bevat accessToken

      6. Toegangstoken is klaar voor gebruik

  2. URL voor webkiosk voorbereiden

    1. Ga naar http://go.cobundu.com (gebruiker heeft de rol van beheerder of ontwikkelaar nodig) > Kioskmodus

    2. Selecteer de relevante verdieping > open webkiosk

    3. Web Kiosk URL heeft het volgende formaat https://go.cobundu.com/kiosk/MEETING%7C1d18e8b0-48a7-464c-8813-66608b474d6d

    4. Vervang het hoofddomein van de URL om het juiste cloud-eindpunt (EU of VS) aan te geven, dan krijg je bijv. https://go.eu1.cloud.cobundu.com/kiosk/MEETING ...

    5. Voeg achtervoegsel "?jwt=" toe en kopieer/plak accessToken aan het einde van de URL

  3. Toegang tot deze URL (bijvoorbeeld in incognitomodus) en de webkiosk zal openen op de gekozen verdieping zonder om identificatie te vragen. Elke 10 minuten wordt een sessie vernieuwd binnen de toepassing.

    1. Nadat de token is verkregen, heb je 10 minuten om deze door te geven in de URL om de plattegrond te openen.

    2. Nadat de plattegrond is geladen, wordt het vernieuwen van de token automatisch uitgevoerd zonder sessieverlies of handmatige tussenkomst.

Beperkingen

  • Webkiosk toont reserveringsweergave (= gecombineerde bezettingsgraad- en reserveringsgegevens (indien beschikbaar))

  • Als browser crasht/computer is losgekoppeld: herstart het proces om een nieuw toegangstoken te krijgen

Zoek op

  • No labels