Dotazování zařízení s využitím rozhraní IoT Central REST API

  • Článek
  • 6 min ke čtení

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. K dotazování zařízení v aplikaci IoT Central můžete použít rozhraní REST API. Tady jsou příklady použití rozhraní REST API pro dotazy:

  • Získejte posledních 10 hodnot telemetrie hlášených zařízením.
  • Získejte posledních 24 hodin dat ze zařízení, která jsou ve stejné místnosti. Místnost je vlastnost zařízení nebo cloudu.
  • Vyhledejte všechna zařízení, která jsou ve stavu chyby a mají zastaralý firmware.
  • Trendy telemetrie ze zařízení v průměru v 10minutových oknech
  • Získejte aktuální verzi firmwaru všech vašich termostatových zařízení.

Tento článek popisuje, jak pomocí /query rozhraní API dotazovat zařízení.

Zařízení může seskupit vlastnosti, telemetrii a příkazy, které podporuje, do komponent a modulů.

Každé volání rozhraní REST API služby IoT Central vyžaduje autorizační hlavičku. Další informace najdete v tématu Ověřování a autorizace volání rozhraní REST API služby IoT Central.

Referenční dokumentaci k rozhraní IOT Central REST API najdete v referenčních informacích k rozhraní REST API služby Azure IoT Central.

Tip

Pomocí Nástroje Postman můžete vyzkoušet volání rozhraní REST API popsaná v tomto článku. Stáhněte si kolekci IoT Central Postman a naimportujte ji do Postmanu. V kolekci budete muset nastavit proměnné, jako je subdoména aplikace a token správce.

Informace o dotazování zařízení pomocí uživatelského rozhraní IoT Central najdete v tématu Použití Průzkumníka dat k analýze dat zařízení.

Spuštění dotazu

Pomocí následujícího požadavku spusťte dotaz:

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

Dotaz je v textu požadavku a vypadá jako v následujícím příkladu:

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

Hodnota dtmi:azurertos:devkit:hlby5jgib2o v klauzuli FROM je ID šablony zařízení. Pokud chcete najít ID šablony zařízení, přejděte ve své aplikaci IoT Central na stránku Zařízení a najeďte myší na zařízení, které šablonu používá. Karta obsahuje ID šablony zařízení:

Snímek obrazovky, který ukazuje, jak najít ID šablony zařízení v adrese URL stránky

Odpověď zahrnuje telemetrii z více zařízení, která sdílejí stejnou šablonu zařízení. Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Syntaxe dotazu se podobá syntaxi SQL a skládá se z následujících klauzulí:

  • SELECT je povinný a definuje data, která chcete načíst, například hodnoty telemetrie zařízení.
  • FROM je povinný a identifikuje typ zařízení, na který se dotazujete. Tato klauzule určuje ID šablony zařízení.
  • WHERE je nepovinný a umožňuje filtrovat výsledky.
  • ORDER BY je nepovinný a umožňuje seřadit výsledky.
  • GROUP BY je nepovinný a umožňuje agregovat výsledky.

Následující části popisují tyto klauzule podrobněji.

Klauzule SELECT

Klauzule SELECT uvádí hodnoty dat, které se mají zahrnout do výstupu dotazu, a může obsahovat následující položky:

  • Telemetrie. Použijte názvy telemetrických dat ze šablony zařízení.
  • Ohlášené vlastnosti Použijte názvy vlastností ze šablony zařízení.
  • Vlastnosti cloudu. Použijte názvy cloudových vlastností ze šablony zařízení.
  • $id. ID zařízení.
  • $provisioned. Logická hodnota, která ukazuje, jestli je zařízení ještě zřízené.
  • $simulated. Logická hodnota, která ukazuje, jestli je zařízení simulované zařízení.
  • $ts. Časové razítko přidružené k hodnotě telemetrie.

Pokud vaše šablona zařízení používá komponenty, jako je součást Informace o zařízení , pak odkazujete na telemetrii nebo vlastnosti definované v této komponentě následujícím způsobem:

{
  "query": "SELECT deviceInformation.model, deviceInformation.swVersion FROM dtmi:azurertos:devkit:hlby5jgib2o"
}

Název komponenty najdete v šabloně zařízení:

Snímek obrazovky, který ukazuje, jak najít název komponenty

V klauzuli SELECT platí následující limity:

  • Neexistuje žádný operátor se zástupným znakem.
  • V seznamu pro výběr nemůžete mít více než 15 položek.
  • V jednom dotazu buď vyberete telemetrii, nebo vlastnosti, ale ne obojí. Dotaz na vlastnosti může obsahovat ohlášené vlastnosti i vlastnosti cloudu.

Aliasy

Pomocí klíčového AS slova definujte alias pro položku v klauzuli SELECT . Alias se používá ve výstupu dotazu. Můžete ho také použít jinde v dotazu. Příklad:

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

Tip

Jako alias nemůžete použít jinou položku v seznamu pro výběr. Například následující možnost není povolená SELECT id, temp AS id....

Výsledek vypadá jako následující výstup:

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

TOP Použijte k omezení počtu výsledků, které dotaz vrátí. Například následující dotaz vrátí prvních 10 výsledků:

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

Pokud dotaz nepoužíváte TOP, vrátí maximálně 10 000 výsledků.

Pokud chcete výsledky seřadit před TOP omezením počtu výsledků, použijte ORDER BY.

Klauzule FROM

Klauzule FROM musí obsahovat ID šablony zařízení. Klauzule FROM určuje typ zařízení, na které dotazujete.

Pokud chcete najít ID šablony zařízení, přejděte ve své aplikaci IoT Central na stránku Zařízení a najeďte myší na zařízení, které šablonu používá. Karta obsahuje ID šablony zařízení:

Snímek obrazovky, který ukazuje, jak najít ID šablony zařízení v adrese URL stránky

K získání ID šablony zařízení pro zařízení můžete použít také zařízení – Získání volání rozhraní REST API.

Klauzule WHERE

Klauzule WHERE umožňuje použít hodnoty a časová okna k filtrování výsledků:

Časová okna

Pokud chcete získat telemetrii přijatou vaší aplikací v zadaném časovém intervaluWHERE, použijte WITHIN_WINDOW ji jako součást klauzule. Pokud například chcete načíst telemetrii teploty a vlhkosti za poslední den, použijte následující dotaz:

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

Hodnota časového intervalu používá formát doby trvání ISO 8601. Následující tabulka obsahuje některé příklady:

Příklad Description
PT10M Posledních 10 minut
P1D Minulý den
P2DT12H Posledních 2 dní a 12 hodin
P1W Minulý týden
PT5H Posledních pět hodin
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z' Konkrétní časový rozsah

Poznámka

Časové intervaly můžete použít jenom při dotazování na telemetrii.

Porovnání hodnot

Můžete získat telemetrická data nebo hodnoty vlastností na základě konkrétních hodnot. Následující dotaz například vrátí všechny zprávy, ve kterých je teplota větší než nula, tlak je větší než 50 a ID zařízení je jedním z vzorků 002 a sample-003:

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

Podporují se následující operátory:

  • Logické operátory AND a OR.
  • Relační operátory =, <>=><=!=, , <>a .IN

Poznámka

Operátor IN funguje jenom s telemetrií a $id.

V klauzuli WHERE platí následující limity:

  • V jednom dotazu můžete použít maximálně 10 operátorů.
  • V dotazu WHERE telemetrie může klauzule obsahovat pouze filtry telemetrie a metadat zařízení.
  • V dotazu WHERE na vlastnost může klauzule obsahovat pouze ohlášené vlastnosti, vlastnosti cloudu a filtry metadat zařízení.

Agregace a klauzule GROUP BY

Funkce agregace umožňují vypočítat hodnoty, jako je průměr, maximum a minimum dat telemetrie v časovém intervalu. Například následující dotaz vypočítá průměrnou teplotu a vlhkost ze zařízení sample-001 v 10minutových oknech:

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

Výsledky vypadají jako následující výstup:

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

Podporují se následující agregační funkce: SUM, MINAVGFIRSTMAXCOUNTa .LAST

Slouží GROUP BY WINDOW k určení velikosti okna. Pokud nepoužíváte GROUP BY WINDOW, dotaz agreguje telemetrii za posledních 30 dnů.

Poznámka

Můžete agregovat pouze hodnoty telemetrie.

Klauzule ORDER BY

Klauzule ORDER BY umožňuje seřadit výsledky dotazu podle hodnoty telemetrie, časového razítka nebo ID zařízení. Můžete řadit vzestupně nebo sestupně. Například následující dotaz nejprve vrátí nejnovější výsledky:

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

Tip

Zkombinujte ORDER BY s TOP cílem omezit počet výsledků, které dotaz vrátí po řazení.

Omezení

Aktuální limity pro dotazy jsou:

  • V seznamu klauzulí není více než 15 položek SELECT .
  • V klauzuli WHERE není více než 10 logických operací.
  • Dotazy vrací maximálně 10 000 záznamů.
  • Maximální délka řetězce dotazu je 350 znaků.
  • Zástupný znak (*) v SELECT seznamu klauzulí nemůžete použít.

Další kroky

Teď, když jste se dozvěděli, jak dotazovat zařízení pomocí rozhraní REST API, je navrhovaným dalším krokem informace o tom, jak používat rozhraní IOT Central REST API ke správě uživatelů a rolí.