Använda IoT Central REST API till att köra frågor mot enheter

  • Artikel

Med REST API för IoT Central kan du utveckla klientprogram som integreras med IoT Central-program. Du kan använda REST-API:et för att fråga enheter i ditt IoT Central-program. Följande är exempel på hur du kan använda frågans REST API:

  • Hämta de senaste 10 telemetrivärdena som rapporterats av en enhet.
  • Hitta alla enheter som har ett feltillstånd och som har inaktuell inbyggd programvara.
  • Telemetritrender från enheter, i genomsnitt i 10-minutersfönster.
  • Hämta den aktuella versionen av inbyggd programvara för alla dina termostatenheter.

I den här artikeln beskrivs hur du använder API:et /query för att fråga enheter.

En enhet kan gruppera egenskaper, telemetri och kommandon som den stöder i komponenter och moduler.

Varje IoT Central REST API-anrop kräver ett auktoriseringshuvud. Mer information finns i Autentisera och auktorisera IoT Central REST API-anrop.

Referensdokumentationen för REST API:et för IoT Central finns i Referens för Rest API för Azure IoT Central.

Dricks

Du kan använda Postman för att prova REST API-anropen som beskrivs i den här artikeln. Ladda ned IoT Central Postman-samlingen och importera den till Postman. I samlingen måste du ange variabler som appens underdomän och administratörstoken.

Information om hur du kör frågor mot enheter med hjälp av användargränssnittet för IoT Central finns i Så här använder du datautforskaren för att analysera enhetsdata.

Köra en fråga

Använd följande begäran för att köra en fråga:

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

Frågan finns i begärandetexten och ser ut som i följande exempel:

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

Värdet dtmi:eclipsethreadx:devkit:hlby5jgib2o i FROM -satsen är ett enhetsmalls-ID. Om du vill hitta ett enhetsmalls-ID går du till sidan Enheter i ditt IoT Central-program och hovra över en enhet som använder mallen. Kortet innehåller enhetsmallens ID:

Skärmbild som visar hur du hittar enhetsmallens ID i sid-URL:en.

Svaret innehåller telemetri från flera enheter som delar samma enhetsmall. Svaret på den här begäran ser ut som i följande exempel:

{
  "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
    }
  ]
}

Syntax

Frågesyntaxen liknar SQL-syntaxen och består av följande satser:

  • SELECT krävs och definierar de data som du vill hämta, till exempel enhetens telemetrivärden.
  • FROM krävs och identifierar den enhetstyp som du frågar efter. Den här satsen anger enhetsmallens ID.
  • WHERE är valfritt och låter dig filtrera resultatet.
  • ORDER BY är valfritt och låter dig sortera resultatet.
  • GROUP BY är valfritt och låter dig aggregera resultat.

I följande avsnitt beskrivs dessa satser mer detaljerat.

SELECT-satsen

Satsen SELECT visar de datavärden som ska inkluderas i frågeutdata och kan innehålla följande objekt:

  • Telemetri. Använd telemetrinamnen från enhetsmallen.
  • $id. Enhets-ID:t.
  • $provisioned. Ett booleskt värde som visar om enheten har etablerats ännu.
  • $simulated. Ett booleskt värde som visar om enheten är en simulerad enhet.
  • $ts. Tidsstämpeln som är associerad med ett telemetrivärde.

Om enhetsmallen använder komponenter refererar du till telemetri som definierats i komponenten enligt följande:

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

Du hittar komponentnamnet i enhetsmallen:

Skärmbild som visar hur du hittar komponentnamnet.

Följande begränsningar gäller i SELECT -satsen:

  • Det finns ingen jokerteckenoperator.
  • Du kan inte ha fler än 15 objekt i urvalslistan.
  • En fråga returnerar högst 10 000 poster.

Alias

Använd nyckelordet AS för att definiera ett alias för ett objekt i SELECT -satsen. Aliaset används i frågeutdata. Du kan också använda den någon annanstans i frågan. Till exempel:

{
  "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"
}

Dricks

Du kan inte använda ett annat objekt i urvalslistan som alias. Följande är till exempel inte tillåtet SELECT id, temp AS id....

Resultatet ser ut som följande utdata:

{
  "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
    }
  ]
}

TOPP

TOP Använd för att begränsa antalet resultat som frågan returnerar. Följande fråga returnerar till exempel de första 10 resultaten:

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

Om du inte använder TOPreturnerar frågan högst 10 000 resultat.

Om du vill sortera resultatet innan TOP begränsas antalet resultat använder du ORDER BY.

FROM-sats

Satsen FROM måste innehålla ett enhetsmalls-ID. Satsen FROM anger vilken typ av enhet du kör frågor mot.

Om du vill hitta ett enhetsmalls-ID går du till sidan Enheter i ditt IoT Central-program och hovra över en enhet som använder mallen. Kortet innehåller enhetsmallens ID:

Skärmbild som visar hur du hittar enhetsmallens ID på enhetssidan.

Du kan också använda anropet Enheter – Hämta REST API för att hämta enhetsmallens ID för en enhet.

WHERE-satsen

Med WHERE satsen kan du använda värden och tidsfönster för att filtrera resultatet:

Tidsfönster

Om du vill få telemetri som tas emot av ditt program inom ett angivet tidsfönster använder du WITHIN_WINDOW som en del av WHERE -satsen. Om du till exempel vill hämta telemetri för temperatur och luftfuktighet för den senaste dagen använder du följande fråga:

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

Tidsfönstrets värde använder formatet ISO 8601 durations. Följande tabell innehåller några exempel:

Exempel beskrivning
PT10M Senaste 10 minuterna
P1D Tidigare dag
P2DT12H Senaste 2 dagarna och 12 timmarna
P1W Senaste veckan
PT5H Senaste fem timmarna
"2021-06-13T13:00:00Z/2021-06-13T15:30:00Z" Specifikt tidsintervall

Värdejämförelser

Du kan hämta telemetri baserat på specifika värden. Följande fråga returnerar till exempel alla meddelanden där temperaturen är större än noll, trycket är större än 50 och enhets-ID:t är ett av sample-002 och sample-003:

{
  "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']"
}

Följande operatorer stöds:

  • Logiska operatorer AND och OR.
  • Jämförelseoperatorer =, !=, >, <, >=, <=, <>och IN.

Kommentar

Operatorn IN fungerar bara med telemetri och $id.

Följande begränsningar gäller i WHERE -satsen:

  • Du kan använda högst 10 operatorer i en enda fråga.
  • I en fråga WHERE kan satsen endast innehålla telemetri- och enhetsmetadatafilter.
  • I en fråga kan du hämta upp till 10 000 poster.

Sammansättningar och GROUP BY-sats

Med aggregeringsfunktioner kan du beräkna värden som medelvärde, max och minimum för telemetridata inom en tidsperiod. Följande fråga beräknar till exempel genomsnittlig temperatur och luftfuktighet från enheten sample-001 i 10-minutersfönster:

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

Resultatet ser ut som följande utdata:

{
    "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
        }
    ]
}

Följande aggregeringsfunktioner stöds: SUM, MAX, MIN, COUNT, AVG, FIRSToch LAST.

Använd GROUP BY WINDOW för att ange fönsterstorleken. Om du inte använder GROUP BY WINDOWaggregerar frågan telemetrin under de senaste 30 dagarna.

Kommentar

Du kan bara aggregera telemetrivärden.

ORDER BY-satsen

Med ORDER BY satsen kan du sortera frågeresultaten efter ett telemetrivärde, tidsstämpeln eller enhets-ID:t. Du kan sortera i stigande eller fallande ordning. Följande fråga returnerar till exempel de senaste resultaten först:

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

Dricks

Kombinera ORDER BY med TOP för att begränsa antalet resultat som frågan returnerar efter sortering.

Gränser

De aktuella gränserna för frågor är:

  • Högst 15 objekt i satslistan SELECT .
  • Högst 10 logiska åtgärder i WHERE -satsen.
  • Den maximala längden på en frågesträng är 350 tecken.
  • Du kan inte använda jokertecknet (*) i satslistan SELECT .
  • Frågor kan hämta upp till 10 000 poster.

Nästa steg

Nu när du har lärt dig hur du frågar enheter med REST-API:et är ett föreslaget nästa steg att lära dig hur du använder REST-API:et för IoT Central för att hantera användare och roller.