Udostępnij za pośrednictwem

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

  • Artykuł

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 reprezentacji urządzeń i bliźniaczych reprezentacji modułów jako pojedynczego dokumentu JSON zawierającego wszystkie informacje o bliźniaczej reprezentacji.

Oto przykładowa reprezentacja urządzenia centrum IoT Hub (bliźniaczą reprezentacja modułu będzie podobna 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 bliźniaczej reprezentacji urządzenia

IoT Hub uwidacznia bliźniacze reprezentacje urządzenia jako kolekcję dokumentów o nazwie urządzenia. Na przykład najbardziej podstawowe zapytanie pobiera cały zestaw bliźniaczych reprezentacji urządzeń:

SELECT * FROM devices

Uwaga

Zestawy SDK usługi Azure IoT 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. Na przykład aby odbierać bliźniacze reprezentacje urządzeń, w których tag location.region jest ustawiony na us , użyj następującego zapytania:

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

Tworzenie złożonych klauzul WHERE przy użyciu operatorów logicznych i porównań arytmetycznych. Na przykład następujące zapytanie pobiera bliźniacze reprezentacje urządzeń znajdujące się w Stanach Zjednoczonych i skonfigurowane do wysyłania danych telemetrycznych mniej 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 (nie w). 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 tę funkcję is_defined() w tym celu. 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 zapoznać się z pełnym odwołaniem do możliwości filtrowania.

Grupowanie jest również obsługiwane. 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ą deweloperom zwracanie tylko właściwości, o których dbają. Aby na przykład pobrać czas ostatniego działania wraz z identyfikatorem urządzenia wszystkich urządzeń, które zostały 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 bliźniaczych reprezentacji modułu jest podobne do wykonywania zapytań dotyczących bliźniaczych reprezentacji urządzeń, ale przy użyciu innej kolekcji/przestrzeni nazw; zamiast z urządzeń wysyłasz zapytania z pliku devices.modules:

SELECT * FROM devices.modules

Nie zezwalamy na dołączanie między kolekcjami devices i 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źniacze reprezentacje modułu ze stanem skanowania, ale tylko w określonym podzestawie urządzeń:

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

Ograniczenia zapytań bliźniaczych reprezentacji

Ważne

Wyniki zapytania są ostatecznie spójne operacje i opóźnienia do 30 minut powinny być tolerowane. W większości przypadków zapytanie bliźniacze zwraca wyniki w kolejności kilku sekund. 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ć pewnego opóźnienia.

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

Wyrażenia zapytania 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 przyjmować zależności od właściwości lastActivityTime w obszarze Właściwości tożsamości urządzenia dla zapytań bliźniaczych reprezentacji w dowolnym 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. Więcej informacji na temat używania zdarzeń cyklu życia IoT Hub w rozwiązaniu można znaleźć w React, aby IoT Hub zdarzenia przy użyciu usługi Event Grid w celu wyzwalania akcji.

Uwaga

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

Następne kroki