Moeilijkheidsgraad: expert
Inhoud
Leerdoelen
Na het lezen van dit artikel kun je:
- de GET Sensor Values API gebruiken in Workplace
Deze pagina bevat meer informatie over de GET Sensor Values API, waarmee je de sensorwaarden kunt exporteren die in Workplace voor je apparaten zijn opgeslagen.
Zie Rest API voor meer informatie over Workplace-API's in het algemeen (best practices voor het benaderen, testen, valideren en oplossen van problemen met API's).
De GET Sensor Values API bevat 3 velden om aan te geven welke gegevens je wilt ophalen: Apparaat-ID en de velden Van-datum/-tijd en Tot-datum/-tijd.
Deze pagina bevat enkele tips en trucs om zo goed mogelijk met deze velden te werken.
Van-tot-datum-/tijdvelden
- Geef specifieke datum-tijdinformatie op volgens de ISO 8601-indeling (bijvoorbeeld: 2025-02-16T10:00:00+01:00) om concrete gegevens voor dat tijdsbestek op te halen
- Vul “latest” in het veld Van in en laat het veld Tot leeg om alleen de meest recente waarde op te halen die beschikbaar is in de database van Workplace
Waarschuwing
Deze API kan geen bereik van meer dan één dag retourneren. Beperk de periode tussen de Van- en Tot-aanvraag daarom tot maximaal 24 uur
Veld Apparaat-ID
Geef in het veld Apparaat-ID een Apparaat-ID op volgens de indeling “prefix|Device ID|suffix”. Dit verwijst naar
- de oorspronkelijke bron van de gegevens (voordat deze in Workplace terechtkwamen) (zie hieronder “Voorvoegsel”),
- de unieke apparaatidentificatie zoals deze bekend is in de database van Workplace (zie hieronder “Apparaat-ID”) en
- het exacte sensortype waarvoor je gegevens wilt ontvangen (zie hieronder “Achtervoegsel”).
Info
Omdat er veel componenten en mogelijke afwijkingen zijn bij het gebruik van de GET SensorValues API, moet je ten minste 1 apparaat-ID testen in de Workplace API-test om je aanvraag te valideren.
Voorvoegsel
Het voorvoegsel verwijst naar de oorspronkelijke bron van de gegevens (voordat deze in Workplace terechtkwamen):
- gebruik voor alle Spacewell LoRa-apparaten “tracknet” (zie Sensors)
- gebruik voor propriëtaire apparaten zoals Pointgrab, VergeSense, Xovis, Signify enzovoort de naam van deze leverancier (“pointgrab”, “vergesense”, “xovis”, “signify”)
- gebruik voor apparaten waarvan de gegevens via Generic Endpoint worden ingevuld de Device Type ID zoals geconfigureerd in het Custom Device Type (zie Custom Device Types), meestal voorafgegaan door “generic|”.
Apparaat-ID
De Apparaat-ID verwijst naar de unieke apparaatidentificatie zoals deze bekend is in de database van Workplace. In de meeste gevallen is dit de Apparaat-ID die wordt vermeld in het Studio Device Overview (en de Device Export). Soms is deze echter anders. Daarom raden we aan altijd de apparaat-ID te controleren die wordt vermeld in de Studio Device Label-URL (zie Sensors administration).
Als algemene regel kunnen we stellen dat je de URL van het apparaat het beste kunt controleren als Studio een apparaat-ID toont die tot een van de volgende categorieën behoort:
- als de apparaat-ID in Studio Device Overview een pipe (|) of dubbele punt (:) bevat
- als de apparaatgegevens via Generic Endpoint binnenkomen (zie External Data Sources)
Info
Afhankelijk van de browser kun je het te gebruiken voorvoegsel en de apparaat-ID voor de GET API-aanvraag direct controleren aan de hand van wat er in de URL staat achter “https://studio.cobundu.com/…/devices/”. Het kan ook zijn dat de browser het pipe-teken codeert als “%7C”. In dat geval moet je hiermee werken of eromheen lezen.
Voorbeeld van hoe een apparaat-ID in de URL wordt weergegeven
In dit voorbeeld bekijken we een VergeSense-apparaat dat in Studio Device Overview (en Device Export) wordt vermeld met de apparaat-ID “spacewell|Spacewell-Arnhem|Floor 1|1.01”.
Deze “mooie” apparaat-ID wordt door Workplace samengesteld op basis van de informatie die door VergeSense wordt verstrekt. De echte apparaat-ID zoals deze bekend is in de database van Workplace is echter anders, zoals blijkt wanneer we de URL in het Device Label controleren (zie Sensors administration).
In de URL zien we dat de apparaat-ID in de database “B6B662F080F2FEA967F903B8A3D8807B” is.
In de bovenstaande schermafbeelding is je misschien opgevallen dat de URL achter “https://studio.cobundu.com/…/devices/” “vergesense|B6B662F080F2FEA967F903B8A3D8807B” bevat. Dit is inderdaad het voorvoegsel en de apparaat-ID die we nodig hebben in de GET Sensor Values API.
Helaas gebruikt niet elke browser het pipe-teken, zoals je hieronder kunt zien:
Bekijk https://en.wikipedia.org/wiki/Percent-encoding voor meer informatie over de juiste codering van speciale tekens.
Achtervoegsel
Gebruik het achtervoegsel van je aanvraag om aan te geven voor welk exact sensortype je gegevens wilt ontvangen. Als je een comfortsensor hebt en de gegevens voor luchtvochtigheid en temperatuur wilt ophalen, moet je 2 aanvragen naar de API sturen: één voor “prefix|Device ID|humidity” en één voor “prefix|Device ID|temperature”.
Gebruik deze tabel om het achtervoegsel voor je aanvraag te bepalen:
| Sensortype ingeschakeld in Workplace | te gebruiken achtervoegsel in SensorValues API |
|---|---|
| Temperatuur | temperature |
| CO2 | co2 |
| Luchtvochtigheid | humidity |
| VOC | voc |
| Licht % | light-pct |
| Radon | radon |
| Druk | pressure |
| Aanwezigheid | pir |
| Personentelling | headcount |
| Passanten (in) | in |
| Passanten (uit) | out |
| Puls | door |
| Batterij | battery |
Als je niet zeker weet welk sensortype voor je sensor is ingeschakeld in Workplace, controleer dan Devices Overview of Devices Advanced Export (zie Sensors administration). Het Device Label-scherm bevat ook informatie over de ingeschakelde sensoren voor dit apparaat.
Info
Voor de meeste LoRa-sensoren is Devices Advanced Export een uitstekende manier om te beginnen en je lijst op te bouwen, omdat je de gegevens in de kolom “Device ID” kunt samenvoegen met de gegevens in de kolom “Channel”.
Vergeet niet
- het voorvoegsel “tracknet”
- het pipe-teken (|) tussen alle elementen om de indeling “prefix|Device ID|suffix” te volgen
Info
Omdat er veel componenten en mogelijke afwijkingen zijn bij het gebruik van de GET SensorValues API, moet je ten minste 1 apparaat-ID testen in de Workplace API-test om je aanvraag te valideren.
Voorbeelden
Voorbeeld van “prefix|Device ID|suffix” voor gebruik in SensorValues API: Browan Motion
- De Browan-bewegingssensor is een LoRa-apparaat (zie Sensors). Volgens de bovenstaande instructies moeten we “tracknet” als voorvoegsel gebruiken
- apparaat-ID volgens Device Overview: “E8-E1-E1-00-01-09-27-25” → laten we voor 100% zekerheid de Device Device Label-URL controleren (zie Sensors administration)
- voorvoegsel + apparaat-ID volgens URL: tracknet|E8-E1-E1-00-01-09-27-25
- achtervoegsel: “pir” om waarden voor Aanwezigheid te controleren
→ voeg dit samen om gegevens op te halen via de SensorValues API: tracknet|E8-E1-E1-00-01-09-27-25|pir
Dit bevestigt de volgende regel: Voor de meeste LoRa-sensoren is Devices Advanced Export een uitstekende manier om te beginnen en je lijst op te bouwen, omdat je de gegevens in de kolom “Device ID” kunt samenvoegen met de gegevens in de kolom “Channel”:
Resultaat in SensorValues API voor tracknet|E8-E1-E1-00-01-09-27-25|pir
Voorbeeld van “prefix|Device ID|suffix” voor gebruik in SensorValues API: Xovis
- Xovis is een propriëtair apparaat. Volgens de bovenstaande instructies moeten we “xovis” als voorvoegsel gebruiken
- apparaat-ID volgens Device Overview: 00:6E:02:00:C2:E8-1002 → dit ziet er verdacht uit vanwege de dubbele punten… laten we de Device Device Label-URL controleren (zie Sensors administration)
- voorvoegsel + apparaat-ID volgens URL: xovis|006E0200C2E8-1002
- achtervoegsels: “in” en “out” om waarden voor Passanten (in) en Passanten (uit) te controleren
→ voeg dit samen om gegevens op te halen via de SensorValues API: xovis|006E0200C2E8-1002|in en xovis|006E0200C2E8-1002|out
Resultaat in SensorValues API voor xovis|006E0200C2E8-1002|in en xovis|006E0200C2E8-1002|out
Probleemoplossing
Bekijk de best practices in Rest API