IoT Central REST API gebruiken om query's uit te voeren op apparaten

Met de REST API van IoT Central kunt u clienttoepassingen ontwikkelen die kunnen worden geïntegreerd met IoT Central-toepassingen. U kunt de REST API gebruiken om een query uit te voeren op apparaten in uw IoT Central-toepassing. Hier volgen enkele voorbeelden van hoe u de REST API voor query's kunt gebruiken:

• Haal de laatste tien telemetriewaarden op die door een apparaat zijn gerapporteerd.
• Zoek alle apparaten met een foutstatus en verouderde firmware.
• Telemetrietrends van apparaten, gemiddeld in vensters van 10 minuten.
• Haal de huidige firmwareversie van al uw thermostaatapparaten op.

In dit artikel wordt beschreven hoe u de /query API gebruikt om een query uit te voeren op apparaten.

Een apparaat kan de eigenschappen, telemetrie en opdrachten groeperen die worden ondersteund in onderdelen en modules.

Elke IoT Central REST API-aanroep vereist een autorisatieheader. Zie IoT Central REST API-aanroepen verifiëren en autoriseren voor meer informatie.

Zie de naslaginformatie voor de REST API van IoT Central voor Azure IoT Central.

Zie Data Explorer gebruiken om apparaatgegevens te analyseren voor informatie over het uitvoeren van query's op apparaten met behulp van de IoT Central-gebruikersinterface.

Een query uitvoeren

Gebruik de volgende aanvraag om een query uit te voeren:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

De query bevindt zich in de hoofdtekst van de aanvraag en ziet eruit als in het volgende voorbeeld:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

De dtmi:eclipsethreadx:devkit:hlby5jgib2o waarde in de FROM component is een apparaatsjabloon-id. Als u een apparaatsjabloon-id wilt vinden, gaat u naar de pagina Apparaten in uw IoT Central-toepassing en plaatst u de muisaanwijzer op een apparaat dat gebruikmaakt van de sjabloon. De kaart bevat de apparaatsjabloon-id:

Het antwoord bevat telemetrie van meerdere apparaten die dezelfde apparaatsjabloon delen. Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Syntaxis

De querysyntaxis is vergelijkbaar met de SQL-syntaxis en bestaat uit de volgende componenten:

• SELECT is vereist en definieert de gegevens die u wilt ophalen, zoals de telemetriewaarden van het apparaat.
• FROM is vereist en identificeert het apparaattype waarop u een query uitvoert. Met deze component geeft u de apparaatsjabloon-id op.
• WHERE is optioneel en kunt u de resultaten filteren.
• ORDER BY is optioneel en kunt u de resultaten sorteren.
• GROUP BY is optioneel en kunt u resultaten aggregeren.

In de volgende secties worden deze componenten gedetailleerder beschreven.

SELECT-component

De SELECT component bevat de gegevenswaarden die moeten worden opgenomen in de queryuitvoer en kunnen de volgende items bevatten:

• Telemetrie. Gebruik de telemetrienamen van de apparaatsjabloon.
• $id. De apparaat-id.
• $provisioned. Een Booleaanse waarde die aangeeft of het apparaat nog is ingericht.
• $simulated. Een Booleaanse waarde die aangeeft of het apparaat een gesimuleerd apparaat is.
• $ts. Het tijdstempel dat is gekoppeld aan een telemetriewaarde.

Als uw apparaatsjabloon onderdelen gebruikt, verwijst u als volgt naar telemetrie die in het onderdeel is gedefinieerd:

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

U vindt de onderdeelnaam in de apparaatsjabloon:

De volgende limieten zijn van toepassing in de SELECT component:

• Er is geen jokertekenoperator.
• U kunt niet meer dan 15 items in de selectielijst hebben.
• Een query retourneert maximaal 10.000 records.

Aliassen

Gebruik het AS trefwoord om een alias te definiëren voor een item in de SELECT component. De alias wordt gebruikt in de queryuitvoer. U kunt deze ook elders in de query gebruiken. Voorbeeld:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Tip

U kunt geen ander item in de selectielijst gebruiken als alias. Het volgende is bijvoorbeeld niet toegestaan SELECT id, temp AS id....

Het resultaat ziet eruit als de volgende uitvoer:

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

Gebruik de functie TOP om het aantal resultaten te beperken dat de query retourneert. De volgende query retourneert bijvoorbeeld de eerste tien resultaten:

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Als u dit niet gebruikt TOP, retourneert de query maximaal 10.000 resultaten.

Als u de resultaten wilt sorteren voordat TOP het aantal resultaten wordt beperkt, gebruikt u ORDER BY.

FROM-component

De FROM component moet een apparaatsjabloon-id bevatten. Met FROM de component wordt het type apparaat opgegeven waarop u een query uitvoert.

Als u een apparaatsjabloon-id wilt vinden, gaat u naar de pagina Apparaten in uw IoT Central-toepassing en plaatst u de muisaanwijzer op een apparaat dat gebruikmaakt van de sjabloon. De kaart bevat de apparaatsjabloon-id:

U kunt ook de aanroep Apparaten - REST API ophalen om de apparaatsjabloon-id voor een apparaat op te halen.

WHERE-component

Met WHERE de component kunt u waarden en tijdvensters gebruiken om de resultaten te filteren:

Tijdvensters

Als u telemetrie wilt ontvangen door uw toepassing binnen een bepaald tijdvenster, gebruikt WITHIN_WINDOW u deze als onderdeel van de WHERE component. Als u bijvoorbeeld telemetriegegevens over temperatuur en vochtigheid voor de afgelopen dag wilt ophalen, gebruikt u de volgende query:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

De tijdvensterwaarde maakt gebruik van de ISO 8601-duurnotatie. De volgende tabel bevat enkele voorbeelden:

Opmerking	Beschrijving
PT10M	Afgelopen 10 minuten
P1D	Afgelopen dag
P2DT12H	Afgelopen 2 dagen en 12 uur
P1W	Afgelopen week
PT5H	Afgelopen vijf uur
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z'	Specifiek tijdsbereik

Waardevergelijkingen

U kunt telemetrie ophalen op basis van specifieke waarden. Met de volgende query worden bijvoorbeeld alle berichten geretourneerd waarbij de temperatuur groter is dan nul, de druk groter is dan 50 en de apparaat-id een van de sample-002 en sample-003 is:

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

De volgende operators worden ondersteund:

• Logische operators AND en OR.
• Vergelijkingsoperatoren , , , >, <>=, , <=, en <>IN. !==

Notitie

De IN operator werkt alleen met telemetrie en $id.

De volgende limieten zijn van toepassing in de WHERE component:

• U kunt maximaal 10 operators in één query gebruiken.
• In een query kan de WHERE component alleen telemetrie- en apparaatmetagegevensfilters bevatten.
• In een query kunt u maximaal 10.000 records ophalen.

Aggregaties en GROUP BY-component

Met aggregatiefuncties kunt u waarden zoals gemiddelde, maximum en minimum berekenen voor telemetriegegevens binnen een tijdvenster. De volgende query berekent bijvoorbeeld de gemiddelde temperatuur en vochtigheid van het apparaat sample-001 in vensters van 10 minuten:

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

De resultaten zien eruit als de volgende uitvoer:

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

De volgende aggregatiefuncties worden ondersteund: SUM, MAX, MIN, COUNT, AVG, , en FIRSTLAST.

Hiermee GROUP BY WINDOW geeft u de venstergrootte op. Als u dit niet gebruikt GROUP BY WINDOW, worden de telemetriegegevens in de afgelopen 30 dagen samengevoegd met de query.

Notitie

U kunt alleen telemetriewaarden aggregeren.

ORDER BY-component

ORDER BY Met de component kunt u de queryresultaten sorteren op een telemetriewaarde, de tijdstempel of de apparaat-id. U kunt sorteren in oplopende of aflopende volgorde. De volgende query retourneert bijvoorbeeld eerst de meest recente resultaten:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

Tip

Combineer ORDER BY met TOP om het aantal resultaten te beperken dat de query retourneert na het sorteren.

Limieten

De huidige limieten voor query's zijn:

• Niet meer dan 15 items in de SELECT componentenlijst.
• Niet meer dan 10 logische bewerkingen in de WHERE component.
• De maximale lengte van een queryreeks is 350 tekens.
• U kunt het jokerteken (*) niet gebruiken in de SELECT lijst met componenten.
• Query's kunnen maximaal 10.000 records ophalen.

Volgende stappen

Nu u hebt geleerd hoe u query's kunt uitvoeren op apparaten met de REST API, is een voorgestelde volgende stap om te leren hoe u de IoT Central REST API gebruikt om gebruikers en rollen te beheren.