Udostępnij za pośrednictwem

Jak wykonywać zapytania dotyczące urządzeń przy użyciu interfejsu API REST usługi IoT Central

  • Artykuł

Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich, które integrują się z aplikacjami usługi IoT Central. Interfejs API REST umożliwia wykonywanie zapytań dotyczących urządzeń w aplikacji usługi IoT Central. Poniżej przedstawiono przykłady użycia interfejsu API REST zapytań:

  • Pobierz 10 ostatnich wartości telemetrycznych zgłoszonych przez urządzenie.
  • Znajdź wszystkie urządzenia, które są w stanie błędu i mają nieaktualne oprogramowanie układowe.
  • Trendy telemetryczne z urządzeń, średnio w 10-minutowych oknach.
  • Pobierz bieżącą wersję oprogramowania układowego wszystkich urządzeń termostatu.

W tym artykule opisano sposób używania interfejsu /query API do wykonywania zapytań dotyczących urządzeń.

Urządzenie może grupować właściwości, dane telemetryczne i polecenia, które obsługuje w składnikach i modułach.

Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji. Aby dowiedzieć się więcej, zobacz Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central.

Aby uzyskać dokumentację referencyjną interfejsu API REST usługi IoT Central, zobacz Dokumentacja interfejsu API REST usługi Azure IoT Central.

Aby dowiedzieć się, jak wykonywać zapytania dotyczące urządzeń przy użyciu interfejsu użytkownika usługi IoT Central, zobacz Jak używać eksploratora danych do analizowania danych urządzenia.

Uruchamianie zapytania

Użyj następującego żądania, aby uruchomić zapytanie:

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

Zapytanie znajduje się w treści żądania i wygląda jak w poniższym przykładzie:

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

Wartość dtmi:eclipsethreadx:devkit:hlby5jgib2o w klauzuli FROM to identyfikator szablonu urządzenia. Aby znaleźć identyfikator szablonu urządzenia, przejdź do strony Urządzenia w aplikacji usługi IoT Central i umieść kursor na urządzeniu używającym szablonu. Karta zawiera identyfikator szablonu urządzenia:

Zrzut ekranu przedstawiający sposób znajdowania identyfikatora szablonu urządzenia w adresie URL strony.

Odpowiedź zawiera dane telemetryczne z wielu urządzeń, które współdzielą ten sam szablon urządzenia. Odpowiedź na to żądanie wygląda następująco:

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

Składnia

Składnia zapytania jest podobna do składni SQL i składa się z następujących klauzul:

  • SELECT jest wymagany i definiuje dane, które chcesz pobrać, takie jak wartości telemetrii urządzenia.
  • FROM jest wymagany i identyfikuje typ urządzenia, którego wykonujesz zapytanie. Ta klauzula określa identyfikator szablonu urządzenia.
  • WHERE jest opcjonalny i umożliwia filtrowanie wyników.
  • ORDER BY jest opcjonalny i umożliwia sortowanie wyników.
  • GROUP BY jest opcjonalny i umożliwia agregowanie wyników.

W poniższych sekcjach opisano te klauzule bardziej szczegółowo.

Klauzula SELECT

Klauzula SELECT zawiera listę wartości danych do uwzględnienia w danych wyjściowych zapytania i może zawierać następujące elementy:

  • Dane telemetryczne. Użyj nazw telemetrii z szablonu urządzenia.
  • $id. Identyfikator urządzenia.
  • $provisioned. Wartość logiczna, która pokazuje, czy urządzenie jest jeszcze aprowizowane.
  • $simulated. Wartość logiczna, która pokazuje, czy urządzenie jest urządzeniem symulowanym.
  • $ts. Sygnatura czasowa skojarzona z wartością telemetrii.

Jeśli szablon urządzenia używa składników, należy odwołać się do telemetrii zdefiniowanej w składniku w następujący sposób:

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

Nazwę składnika można znaleźć w szablonie urządzenia:

Zrzut ekranu przedstawiający sposób znajdowania nazwy składnika.

W klauzuli SELECT obowiązują następujące limity:

  • Nie ma operatora symboli wieloznacznych.
  • Na liście wyboru nie można mieć więcej niż 15 elementów.
  • Zapytanie zwraca maksymalnie 10 000 rekordów.

Aliasy

Użyj słowa kluczowego AS , aby zdefiniować alias elementu w klauzuli SELECT . Alias jest używany w danych wyjściowych zapytania. Możesz również użyć go w innym miejscu w zapytaniu. Na przykład:

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

Napiwek

Nie można użyć innego elementu na liście wyboru jako aliasu. Na przykład następujące wartości nie są dozwolone SELECT id, temp AS id....

Wynik wygląda podobnie do następujących danych wyjściowych:

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

Użyj parametru , TOP aby ograniczyć liczbę wyników zwracanych przez zapytanie. Na przykład następujące zapytanie zwraca pierwsze 10 wyników:

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

Jeśli nie używasz TOPmetody , zapytanie zwraca maksymalnie 10 000 wyników.

Aby posortować wyniki przed TOP ograniczeniem liczby wyników, użyj polecenia ORDER BY.

Klauzula FROM

Klauzula FROM musi zawierać identyfikator szablonu urządzenia. Klauzula FROM określa typ urządzenia, którego wykonujesz zapytanie.

Aby znaleźć identyfikator szablonu urządzenia, przejdź do strony Urządzenia w aplikacji usługi IoT Central i umieść kursor na urządzeniu używającym szablonu. Karta zawiera identyfikator szablonu urządzenia:

Zrzut ekranu przedstawiający sposób znajdowania identyfikatora szablonu urządzenia na stronie urządzeń.

Możesz również użyć wywołania interfejsu API REST Urządzenia — Pobierz go, aby uzyskać identyfikator szablonu urządzenia dla urządzenia.

Klauzula WHERE

Klauzula WHERE umożliwia filtrowanie wyników przy użyciu wartości i okien czasowych:

Okna czasu

Aby uzyskać dane telemetryczne odebrane przez aplikację w określonym przedziale czasu, użyj WITHIN_WINDOW jej jako części klauzuli WHERE . Aby na przykład pobrać dane telemetryczne dotyczące temperatury i wilgotności dla ostatniego dnia, użyj następującego zapytania:

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

Wartość przedziału czasu używa formatu czasów trwania ISO 8601. Poniższa tabela zawiera kilka przykładów:

Przykład opis
PT10M Ostatnie 10 minut
P1D Ostatni dzień
P2DT12H Ostatnie 2 dni i 12 godzin
P1W Ostatni tydzień
PT5H Ostatnie pięć godzin
"2021-06-13T13:00:00Z/2021-06-13T15:30:00Z" Określony zakres czasu

Porównania wartości

Dane telemetryczne można uzyskać na podstawie określonych wartości. Na przykład następujące zapytanie zwraca wszystkie komunikaty, w których temperatura jest większa niż zero, ciśnienie jest większe niż 50, a identyfikator urządzenia jest jednym z przykładów 002 i 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']"
}

Obsługiwane są następujące operatory:

  • Operatory AND logiczne i OR.
  • Operatory =porównania , >>=<<=!=, <>i .IN

Uwaga

Operator IN działa tylko z danymi telemetrycznymi i $id.

W klauzuli WHERE obowiązują następujące limity:

  • W jednym zapytaniu można użyć maksymalnie 10 operatorów.
  • W zapytaniu klauzula WHERE może zawierać tylko filtry telemetrii i metadanych urządzenia.
  • W zapytaniu można pobrać maksymalnie 10 000 rekordów.

Agregacje i klauzula GROUP BY

Funkcje agregacji umożliwiają obliczanie wartości, takich jak średnia, maksimum i minimum danych telemetrycznych w przedziale czasu. Na przykład następujące zapytanie oblicza średnią temperaturę i wilgotność z urządzenia sample-001 w 10-minutowych oknach:

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

Wyniki wyglądają podobnie do następujących danych wyjściowych:

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

Obsługiwane są następujące funkcje agregacji: SUM, , MAX, COUNTMIN, , AVG, FIRSTi LAST.

Użyj GROUP BY WINDOW polecenia , aby określić rozmiar okna. Jeśli nie używasz GROUP BY WINDOWmetody , zapytanie agreguje dane telemetryczne w ciągu ostatnich 30 dni.

Uwaga

Można agregować tylko wartości telemetryczne.

Klauzula ORDER BY

Klauzula ORDER BY umożliwia sortowanie wyników zapytania według wartości telemetrii, znacznika czasu lub identyfikatora urządzenia. Można sortować w kolejności rosnącej lub malejącej. Na przykład następujące zapytanie najpierw zwraca najnowsze wyniki:

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

Napiwek

Połącz ORDER BY z , TOP aby ograniczyć liczbę wyników zwracanych przez zapytanie po sortowaniu.

Limity

Bieżące limity dla zapytań to:

  • Nie więcej niż 15 elementów na SELECT liście klauzul.
  • Nie więcej niż 10 operacji logicznych w klauzuli WHERE .
  • Maksymalna długość ciągu zapytania wynosi 350 znaków.
  • Nie można użyć symbolu wieloznakowego (*) na SELECT liście klauzul.
  • Zapytania mogą pobierać maksymalnie 10 000 rekordów.

Następne kroki

Teraz, gdy wiesz już, jak wykonywać zapytania dotyczące urządzeń przy użyciu interfejsu API REST, sugerowanym następnym krokiem jest poznanie sposobu używania interfejsu API REST usługi IoT Central do zarządzania użytkownikami i rolami.