Język zapytań usługi IoT Hub dla urządzeń, zdublowanych modułów, zadań i trasowania komunikatów

Usługa IoT Hub udostępnia zaawansowany język przypominający język SQL do pobierania informacji dotyczących bliźniaczych reprezentacji urządzeń, bliźniaczych reprezentacji modułów, zadań i routingu komunikatów. W tym artykule przedstawiono następujące elementy:

Aby zobaczyć konkretne przykłady, zobacz Zapytania dotyczące urządzeń i modulów typu bliźniak w IoT Hub lub Zapytania dotyczące zadań w IoT Hub.

Uwaga

Niektóre funkcje wymienione w tym artykule, takie jak przesyłanie komunikatów z chmury do urządzenia, bliźniaczy stan urządzeń i zarządzanie urządzeniami, są dostępne tylko w warstwie standardowej usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy i rozmiaru usługi IoT Hub dla rozwiązania.

Uruchamianie zapytań usługi IoT Hub

Zapytania dotyczące centrum IoT można uruchamiać bezpośrednio w witrynie Azure Portal.

  1. Zaloguj się do witryny Azure Portal i przejdź do centrum IoT Hub.
  2. Wybierz pozycję Zapytania w sekcji Zarządzanie urządzeniami w menu nawigacji.
  3. Wprowadź zapytanie w polu tekstowym i wybierz pozycję Uruchom zapytanie.

Zapytania można również uruchamiać w aplikacjach przy użyciu zestawów SDK usługi Azure IoT i interfejsów API usługi.

Na przykład kod implementowania zapytań usługi IoT Hub można znaleźć w sekcji Przykłady zapytań z zestawami SDK usługi.

Aby uzyskać linki do stron referencyjnych i przykładów zestawu SDK, zobacz Zestawy SDK usługi Azure IoT Hub.

Podstawy zapytania usługi IoT Hub

Każde zapytanie usługi IoT Hub składa się z klauzul SELECT i FROM z opcjonalnymi klauzulami WHERE i GROUP BY.

Zapytania są wykonywane na kolekcji dokumentów JSON, na przykład bliźniaków urządzeń. Klauzula FROM wskazuje kolekcję dokumentów, która ma być iterowana (devices, devices.modules lub devices.jobs).

Następnie filtr w klauzuli WHERE jest stosowany. W przypadku agregacji wyniki tego kroku są grupowane zgodnie z opisem w klauzuli GROUP BY. Dla każdej grupy wiersz jest generowany zgodnie z opisem w klauzuli SELECT.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

Klauzula SELECT

Klauzula SELECT <select_list> jest wymagana w każdym zapytaniu IoT Hub. Określa, jakie wartości są pobierane z zapytania. Określa wartości JSON, które mają być używane do generowania nowych obiektów JSON. Dla każdego elementu filtrowanego (i opcjonalnie pogrupowanego) podzestawu kolekcji FROM faza projekcji generuje nowy obiekt JSON. Ten obiekt jest konstruowany z wartościami określonymi w klauzuli SELECT.

Na przykład:

  • Zwróć wszystkie wartości

    SELECT *

  • Zwracanie określonych właściwości

    SELECT DeviceID, LastActivityTime

  • Zagreguj wyniki zapytania, aby zwrócić liczbę.

    SELECT COUNT() as TotalNumber

Obecnie klauzule wyboru inne niż SELECT są obsługiwane tylko w zapytaniach agregujących na bliźniaczych urządzeniach.

Następująca składnia to gramatyka klauzuli SELECT:

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
    '*'
    | <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
    attribute_name
    | <projection_element> '.' attribute_name
    | <aggregate>

<aggregate> :==
    count()
    | avg(<projection_element>)
    | sum(<projection_element>)
    | min(<projection_element>)
    | max(<projection_element>)

Attribute_name odwołuje się do dowolnej właściwości dokumentu JSON w kolekcji FROM.

Klauzula FROM

Klauzula FROM <from_specification> jest wymagana w każdym zapytaniu usługi IoT Hub. Musi to być jedna z trzech wartości:

  • urządzenia do wykonywania zapytań dotyczących urządzeń-bliźniaczych
  • devices.modules aby zapytać o bliźniacze moduły
  • devices.jobs, aby zapytać o szczegóły zadań dla każdego urządzenia

Na przykład:

  • Pobierz wszystkie bliźniacze urządzenia

    SELECT * FROM devices

Klauzula WHERE

Klauzula jest opcjonalna WHERE <filter_condition> . Określa co najmniej jeden warunek, który dokumenty JSON w kolekcji FROM muszą spełniać, aby zostały uwzględnione w ramach wyniku. Każdy dokument JSON musi spełniać określone warunki, aby wynik był uznany za true i mógł być uwzględniony w rezultacie.

Na przykład:

  • Pobierz wszystkie zadania przeznaczone dla określonego urządzenia

    SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

Dozwolone warunki opisano w sekcji Wyrażenia i warunki .

klauzula GROUP BY

Klauzula jest opcjonalna GROUP BY <group_specification> . Ta klauzula jest wykonywana po filtrze określonym w klauzuli WHERE i przed projekcją określoną w elemecie SELECT. Grupuje dokumenty na podstawie wartości atrybutu. Te grupy są używane do generowania zagregowanych wartości określonych w klauzuli SELECT.

Na przykład:

  • Zwraca liczbę urządzeń, które zgłaszają stan konfiguracji poszczególnych danych telemetrycznych

    SELECT properties.reported.telemetryConfig.status AS status,
  COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status

Obecnie klauzula GROUP BY jest obsługiwana tylko podczas wykonywania zapytań dotyczących bliźniaczych modeli urządzeń.

Uwaga

Group jest obecnie traktowane jako specjalne słowo kluczowe w zapytaniach. Jeśli używasz group jako nazwy właściwości, rozważ otoczenie jej podwójnymi nawiasami, aby uniknąć błędów, jak pokazano w tym przykładzie: SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

Formalna składnia GROUP BY to:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name odwołuje się do dowolnej właściwości dokumentu JSON w kolekcji FROM.

Stronicowanie wyników zapytania

Obiekt zapytania jest tworzony przy użyciu maksymalnego rozmiaru strony mniejszy lub równy 100 rekordów. Aby uzyskać wiele stron, wywołaj metodę nextAsTwin w Node.js SDK lub GetNextAsTwinAsync w metodzie .NET SDK wiele razy. Obiekt zapytania może uwidocznić wiele wartości "dalej", w zależności od wymagań zapytania dotyczących opcji deserializacji. Na przykład obiekt zapytania może zwracać obiekty bliźniacze urządzenia, obiekty zadania lub zwykły kod JSON przy używaniu projekcji.

Wyrażenia i warunki

Na wysokim poziomie wyrażenie jest:

  • Wyznacza instancję typu JSON (taką jak wartość logiczna, liczba, ciąg znaków, tablica lub obiekt).
  • Jest definiowany przez manipulowanie danymi pochodzącymi z dokumentu JSON urządzenia i stałymi przy użyciu wbudowanych operatorów i funkcji.

Warunki to wyrażenia, które dają wartość logiczną. Każda stała inna niż logiczna true jest uważana za fałsz. Ta reguła zawiera null, wartość niezdefiniowaną, dowolny obiekt lub wystąpienie tablicy, dowolny łańcuch znaków oraz wartość logiczną false.

Składnia wyrażeń to:

<expression> ::=
    <constant> |
    attribute_name |
    <function_call> |
    <expression> binary_operator <expression> |
    <create_array_expression> |
    '(' <expression> ')'

<function_call> ::=
    <function_name> '(' expression ')'

<constant> ::=
    <undefined_constant>
    | <null_constant>
    | <number_constant>
    | <string_constant>
    | <array_constant>

<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

Aby zrozumieć, co oznacza każdy symbol w składni wyrażeń, zapoznaj się z następującą tabelą:

Symbol Definicja
nazwa_atrybutu Dowolna właściwość dokumentu JSON w kolekcji FROM .
binary_operator Dowolny operator binarny wymieniony w sekcji Operatory .
function_name Dowolna funkcja wymieniona w sekcji Funkcje .
liczba dziesiętna Liczba zmiennoprzecinkowa wyrażona w notacji dziesiętnej.
hexadecimal_literal Liczba wyrażona przez ciąg "0x", po którym następuje ciąg cyfr szesnastkowych.
string_literal Ciągi Unicode reprezentowane przez sekwencję zero lub więcej znaków Unicode lub sekwencje ucieczki. Literały ciągu są ujęte w pojedyncze lub podwójne cudzysłowy. Dozwolone znaki ucieczki: \', \", \\, \uXXXX dla znaków Unicode zdefiniowanych przez cztery cyfry szesnastkowe.

Operatory

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

Rodzina Operatory
Arytmetyka +, -, *, /, %
Logiczny I, LUB, NIE
Porównanie =, !=, <, >, <=, >=, <>

Functions

Podczas wykonywania zapytań do bliźniaków i zadań jedyną obsługiwaną funkcją jest:

Funkcja opis
IS_DEFINED(właściwość) Zwraca wartość logiczną wskazującą, czy właściwość ma przypisaną wartość (w tym null).

W warunkach tras obsługiwane są następujące funkcje matematyczne:

Funkcja opis
ABS(x) Zwraca wartość bezwzględną (dodatnią) podanego wyrażenia liczbowego.
EXP(x) Zwraca wartość wykładniczą określonego wyrażenia liczbowego (e^x).
POTĘGA(x,y) Zwraca wartość określonego wyrażenia do określonej mocy (x^y).
SQUARE(x) Zwraca kwadrat określonej wartości liczbowej.
SUFIT(x) Zwraca najmniejszą wartość całkowitą równą określonemu wyrażeniu liczbowemu lub większą.
FLOOR(x) Zwraca największą wartość całkowitą równą określonemu wyrażeniu liczbowemu lub mniejszą.
ZNAK(x) Zwraca dodatni znak (+1), zero (0) lub ujemny (-1) określonego wyrażenia liczbowego.
sqrt(x) Zwraca pierwiastek kwadratowy podanej wartości liczbowej.

W warunkach tras obsługiwane są następujące funkcje sprawdzania typów i rzutowań.

Funkcja opis
Numer AS Konwertuje ciąg wejściowy na liczbę. noop jeśli dane wejściowe są liczbą; Undefined jeśli ciąg nie reprezentuje liczby.
IS_ARRAY Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest tablicą.
IS_BOOL Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest wartością logiczną.
JEST_ZDEFINIOWANY Zwraca wartość logiczną wskazującą, czy właściwość jest wartością. Ta funkcja jest obsługiwana tylko wtedy, gdy wartość jest typem pierwotnym. Typy pierwotne obejmują łańcuch znaków, wartość logiczną, liczbę lub null. Funkcja DateTime, typy obiektów i tablice nie są obsługiwane.
IS_NULL Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia ma wartość null.
IS_NUMBER Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest liczbą.
IS_OBJECT Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest obiektem JSON.
IS_PRIMITIVE Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest pierwotny (ciąg, wartość logiczna, numeryczna lub null).
IS_STRING Zwraca wartość logiczną wskazującą, czy typ określonego wyrażenia jest ciągiem.

W warunkach dotyczących tras obsługiwane są następujące funkcje ciągów:

Funkcja opis
CONCAT(x, y, ...) Zwraca ciąg, który jest wynikiem połączenia co najmniej dwóch wartości ciągu.
DŁUGOŚĆ(x) Zwraca liczbę znaków określonego wyrażenia ciągu.
LOWER(x) Zwraca wyrażenie ciągu po przekonwertowaniu danych znakowych wielkich liter na małe litery.
UPPER(x) Zwraca wyrażenie ciągu po przekonwertowaniu danych znakowych małych liter na wielkie litery.
SUBSTRING(ciąg, początek [, długość]) Zwraca część wyrażenia ciągu rozpoczynającą się od określonej pozycji, liczonej od zera, i kontynuuje na określoną długość lub do końca ciągu.
INDEX_OF(łańcuch, fragment) Zwraca pozycję początkową pierwszego wystąpienia drugiego wyrażenia ciągu w pierwszym określonym wyrażeniu ciągu lub -1, jeśli ciąg nie zostanie znaleziony.
STARTS_WITH(x, y) (sprawdza, czy x zaczyna się od y) Zwraca wartość logiczną wskazującą, czy pierwsze wyrażenie ciągu znaków rozpoczyna się od drugiego.
KOŃCZY_SIĘ(x, y) Zwraca wartość logiczną typu Boolean wskazującą, czy pierwszy ciąg znaków kończy się drugim.
CONTAINS(x,y) Zwraca wartość logiczną wskazującą, czy pierwsze wyrażenie ciągu znaków zawiera drugie.

Przykłady zapytań przy użyciu zestawów SDK usługi

Przykład w języku C#

Funkcje zapytania są udostępniane przez zestaw SDK usługi Azure IoT Hub dla .NET w klasie RegistryManager.

Oto przykład prostego zapytania:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

Obiekt zapytania jest tworzony za pomocą parametrów wymienionych w sekcji stronicowanie wyników zapytania. Wiele stron jest pobieranych przez wywołanie GetNextAsTwinAsync metod wiele razy.

przykład Node.js

Funkcjonalność zapytania jest uwidoczniona przez zestaw SDK usługi Azure IoT Hub dla Node.js w obiekcie Registry.

Oto przykład prostego zapytania:

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

Obiekt zapytania jest tworzony za pomocą parametrów wymienionych w sekcji stronicowanie wyników zapytania. Wiele stron jest pobieranych poprzez wielokrotne wywołanie metody nextAsTwin.

Zapytania dotyczące bliźniaków urządzeń i modułów IoT Hub

Bliźniacze reprezentacje urządzeń i bliźniacze reprezentacje modułów mogą zawierać dowolne obiekty JSON jako tagi i właściwości. IoT Hub umożliwia wykonywanie zapytań dotyczących bliźniaczych obiektów urządzeń i modułów jako pojedynczego dokumentu JSON zawierającego wszystkie informacje o bliźniaczych obiektach.

Oto przykładowy bliźniaczy opis urządzenia IoT Hub (bliźniaczy opis modułu będzie podobny, tylko z parametrem moduleId):

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "Disconnected",
    "lastActivityTime": "0001-01-01T00:00:00",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "version": 2,
    "tags": {
        "location": {
            "region": "US",
            "plant": "Redmond43"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300
            },
            "$metadata": {
            ...
            },
            "$version": 4
        },
        "reported": {
            "connectivity": {
                "type": "cellular"
            },
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300,
                "status": "Success"
            },
            "$metadata": {
            ...
            },
            "$version": 7
        }
    }
}

Zapytania cyfrowego bliźniaka urządzenia

IoT Hub udostępnia bliźniaki urządzeń jako kolekcję dokumentów o nazwie urządzenia. Na przykład najbardziej podstawowe zapytanie pobiera pełny zbiór bliźniaków cyfrowych urządzeń:

SELECT * FROM devices

Uwaga

Azure IoT SDKs obsługują stronicowanie dużych wyników.

Wyniki zapytania można agregować przy użyciu klauzuli SELECT. Na przykład następujące zapytanie pobiera liczbę całkowitej liczby urządzeń w centrum IoT:

SELECT COUNT() as totalNumberOfDevices FROM devices

Filtrowanie wyników zapytania przy użyciu klauzuli WHERE. Aby na przykład otrzymać bliźniacze reprezentacje urządzeń, w których location.region tag jest ustawiony na US, użyj następującego zapytania:

SELECT * FROM devices
WHERE tags.location.region = 'US'

Utwórz złożone klauzule WHERE przy użyciu operatorów logicznych i porównań arytmetycznych. Na przykład następujące zapytanie zwraca bliźniaki urządzeń znajdujące się w Stanach Zjednoczonych i skonfigurowane do wysyłania danych telemetrycznych rzadziej niż co minutę.

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

Można również używać stałych tablicowych z operatorami IN i NIN („not in”). Na przykład następujące zapytanie pobiera bliźniacze reprezentacje urządzeń, które zgłaszają łączność sieci Wi-Fi lub przewodową:

SELECT * FROM devices
  WHERE properties.reported.connectivity IN ['wired', 'wifi']

Często konieczne jest zidentyfikowanie wszystkich bliźniaczych reprezentacji urządzeń, które zawierają określoną właściwość. IoT Hub obsługuje w tym celu funkcję is_defined(). Na przykład następujące zapytanie pobiera bliźniacze reprezentacje urządzenia, które definiują connectivity właściwość:

SELECT * FROM devices
  WHERE is_defined(properties.reported.connectivity)

Zapoznaj się z sekcją klauzuli WHERE , aby uzyskać pełną dokumentację funkcji filtrowania.

Obsługiwane jest również grupowanie. Na przykład następujące zapytanie zwraca liczbę urządzeń w każdym stanie konfiguracji telemetrii:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status

To zapytanie grupujące zwróci wynik podobny do następującego przykładu:

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

W tym przykładzie trzy urządzenia zgłosiły pomyślną konfigurację, dwa nadal stosują konfigurację i jeden zgłosił błąd.

Zapytania projekcji umożliwiają programistom zwracanie tylko właściwości, na których im zależy. Aby pobrać na przykład czas ostatniego działania oraz identyfikatory urządzeń wszystkich włączonych urządzeń, które są rozłączone, użyj następującego zapytania:

SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'

Wynik tego zapytania będzie wyglądać podobnie do następującego przykładu:

[
  {
    "deviceId": "AZ3166Device",
    "lastActivityTime": "2021-05-07T00:50:38.0543092Z"
  }
]

Zapytania bliźniaczej reprezentacji modułu

Wykonywanie zapytań dotyczących reprezentacji bliźniaka modułu jest podobne do wykonywania zapytań dotyczących reprezentacji bliźniaka urządzenia, ale przy użyciu innej kolekcji/przestrzeni nazw; zamiast z devices, zapytanie z kolekcji/przestrzeni devices.modules.

SELECT * FROM devices.modules

Nie zezwalamy na łączenie pomiędzy kolekcjami devices a devices.modules. Jeśli chcesz wykonywać zapytania dotyczące bliźniaczych reprezentacji modułów na różnych urządzeniach, zrób to na podstawie tagów. Następujące zapytanie zwraca wszystkie bliźniacze reprezentacje modułu na wszystkich urządzeniach ze stanem skanowania:

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

Następujące zapytanie zwraca wszystkie bliźniaki modułu ze stanem skanowania, ale wyłącznie w przypadku określonego podzestawu urządzeń.

SELECT * FROM devices.modules
  WHERE properties.reported.status = 'scanning'
  AND deviceId IN ['device1', 'device2']

Ograniczenia zapytań bliźniaczych

Ważna

Wyniki zapytania są ostatecznie spójnymi operacjami i powinny być tolerowane opóźnienia do 30 minut. W większości przypadków bliźniacze zapytanie zwraca wyniki w ciągu kilku sekund. Usługa IoT Hub dąży do zapewnienia małych opóźnień dla wszystkich operacji. Jednak ze względu na warunki sieciowe i inne nieprzewidywalne czynniki nie może zagwarantować określonego opóźnienia.

Alternatywną opcją zapytań bliźniaczych jest wykonywanie zapytań dotyczących poszczególnych reprezentacji urządzeń według identyfikatora przy użyciu interfejsu API REST get twin. Ten interfejs API zawsze zwraca najnowsze wartości i ma wyższe limity ograniczania przepustowości. Interfejs API REST można wywołać bezpośrednio lub użyć równoważnej funkcjonalności w jednym z zestawów SDK usługi Azure IoT Hub.

Wyrażenia zapytań mogą mieć maksymalną długość 8192 znaków.

Obecnie porównania są obsługiwane tylko między typami pierwotnymi (bez obiektów), na przykład ... WHERE properties.desired.config = properties.reported.config jest obsługiwane tylko wtedy, gdy te właściwości mają wartości pierwotne.

Zalecamy, aby nie polegać na właściwościach tożsamości urządzenia lastActivityTime w zapytaniach typu "Twin" w żadnym scenariuszu. To pole nie gwarantuje dokładnego miernika stanu urządzenia. Zamiast tego użyj zdarzeń cyklu życia urządzenia IoT do zarządzania stanem i działaniami urządzenia. Aby uzyskać informacje na temat używania zdarzeń cyklu życia w IoT Hub w Twoim rozwiązaniu, zobacz Reagowanie na zdarzenia IoT Hub przy użyciu usługi Event Grid do uruchamiania działań.

Uwaga

Unikaj wprowadzania wszelkich założeń dotyczących maksymalnego opóźnienia tej operacji. Zobacz Rozwiązania opóźnienia , aby uzyskać więcej informacji na temat tworzenia rozwiązania z uwzględnieniem opóźnień.

Zapytania dotyczące zadań IoT Hub

Zadania umożliwiają wykonywanie operacji na zestawach urządzeń. Każdy bliźniak urządzenia zawiera informacje o zadaniach w kolekcji nazywanej zadania. IoT Hub umożliwia wykonywanie zapytań o zadania jako pojedynczy dokument JSON zawierający wszystkie informacje o cyfrowych bliźniakach.

Oto przykład bliźniaczego modelu urządzenia IoT Hub, który jest częścią zadania o nazwie myJobId:

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "tags": {
        ...
    },
    "properties": {
        ...
    },
    "jobs": [
        {
            "deviceId": "myDeviceId",
            "jobId": "myJobId",
            "jobType": "scheduleUpdateTwin",
            "status": "completed",
            "startTimeUtc": "2016-09-29T18:18:52.7418462",
            "endTimeUtc": "2016-09-29T18:20:52.7418462",
            "createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
            "lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
            "outcome": {
                "deviceMethodResponse": null
            }
        },
        ...
    ]
}

Obecnie ta kolekcja może być zapytana jako devices.jobs w języku zapytań IoT Hub.

Ważna

Obecnie właściwość zadań nie jest zwracana podczas wykonywania zapytań dotyczących bliźniaczych urządzeń. Oznacza to, że zapytania zawierające FROM devices. Dostęp do właściwości zadań można uzyskać tylko bezpośrednio za pomocą zapytań przy użyciu polecenia FROM devices.jobs.

Na przykład następujące zapytanie zwraca wszystkie zadania (wcześniejsze i zaplanowane), które mają wpływ na jedno urządzenie:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

Zwróć uwagę, że to zapytanie przedstawia stan specyficzny dla urządzenia (i ewentualnie odpowiedź na metodę bezpośrednią) dla każdego zwróconego zadania.

Istnieje również możliwość filtrowania przy użyciu dowolnych warunków boolowskich we wszystkich właściwościach obiektu w kolekcji devices.jobs.

Na przykład następujące zapytanie pobiera wszystkie ukończone zadania aktualizacji bliźniaczej reprezentacji urządzenia utworzone dla określonego urządzenia po wrześniu 2016 roku.

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'
    AND devices.jobs.jobType = 'scheduleUpdateTwin'
    AND devices.jobs.status = 'completed'
    AND devices.jobs.createdTimeUtc > '2016-09-01'

Możesz również pobrać wyniki dla każdego urządzenia dotyczące pojedynczego zadania.

SELECT * FROM devices.jobs
  WHERE devices.jobs.jobId = 'myJobId'

Ograniczenia zapytań dotyczących zadań

Wyrażenia zapytań mogą mieć maksymalną długość 8192 znaków.

Obecnie zapytania w usłudze devices.jobs nie obsługują:

  • Możliwe są jedynie projekcje SELECT *.
  • Warunki odwołujące się do device twin oprócz atrybutów zadania (zobacz poprzednią sekcję).
  • Agregacje, takie jak liczba, średnia i grupa według.

Treści powiązane

  • Dowiedz się więcej o routingu komunikatów na podstawie właściwości komunikatów lub treści komunikatów przy użyciu składni zapytania routingu komunikatów usługi IoT Hub.
  • Last updated on