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

  • Článek

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

  • Získejte posledních 10 hodnot telemetrie hlášených zařízením.
  • 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 používat /query rozhraní API k dotazování 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 vaší 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

Ke spuštění dotazu použijte následující požadavek:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-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:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Hodnota dtmi:eclipsethreadx:devkit:hlby5jgib2o v FROM klauzuli je ID šablony zařízení. Pokud chcete najít ID šablony zařízení, přejděte v 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
    }
  ]
}

Syntaxe

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í, který 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é mají být zahrnuty do výstupu dotazu, a může obsahovat následující položky:

  • Telemetrická data. Použijte názvy telemetrie 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, odkazujete na telemetrii definovanou v této komponentě následujícím způsobem:

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

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

Snímek obrazovky znázorňující, jak najít název komponenty

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

  • Neexistuje žádný operátor zástupných znaků.
  • V seznamu výběrů nemůžete mít více než 15 položek.
  • Dotaz vrátí maximálně 10 000 záznamů.

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:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Tip

Jako alias nelze použít jinou položku v seznamu výběru. Například následující není povoleno 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:eclipsethreadx: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é se dotazujete.

Pokud chcete najít ID šablony zařízení, přejděte v 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í na stránce zařízení

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

Klauzule WHERE

Klauzule WHERE umožňuje filtrovat výsledky pomocí hodnot a časových oken:

Č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:eclipsethreadx: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ěkolik příkladů:

Příklad Popis
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

Porovnání hodnot

Telemetrii můžete získat 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 vzorku-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']"
}

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

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

Poznámka:

Operátor IN pracuje pouze s telemetrií a $id.

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

  • V jednom dotazu můžete použít maximálně 10 operátorů.
  • V dotazu WHERE může klauzule obsahovat pouze filtry telemetrie a metadat zařízení.
  • V dotazu můžete načíst až 10 000 záznamů.

Agregace a klauzule GROUP BY

Agregační funkce umožňují vypočítat hodnoty, jako je průměr, maximum a minimum u telemetrických dat 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:eclipsethreadx: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, , MINMAX, COUNT, AVG, FIRST, a 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:

Agregovat můžete jenom hodnoty telemetrie.

Klauzule ORDER BY

Klauzule ORDER BY umožňuje ř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 vrátí jako první nejnovější výsledky:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx: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í.
  • Maximální délka řetězce dotazu je 350 znaků.
  • V seznamu klauzulí nemůžete použít zástupný znak (*).SELECT
  • Dotazy můžou načíst až 10 000 záznamů.

Další kroky

Teď, když jste se naučili dotazovat zařízení pomocí rozhraní REST API, je navrhovaným dalším krokem naučit se používat rozhraní IoT Central REST API ke správě uživatelů a rolí.