Udostępnij za pośrednictwem

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. Usługa IoT Hub umożliwia wykonywanie zapytań dotyczących bliźniaków urządzeń i bliźniaków modułów jako pojedynczego dokumentu JSON zawierającego wszystkie informacje o bliźniakach.

Oto przykładowe bliźniacze urządzenie IoT hub (bliźniacze moduły będą podobne, ale 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źniaczego urządzenia

Usługa IoT Hub udostępnia bliźniaki urządzeń jako kolekcję dokumentów nazywaną devices. 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'

Utwórz złożone klauzule 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 wchodzi w skład). 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źniaków urządzeń, które zawierają określoną właściwość. IoT Hub obsługuje funkcję is_defined() do tego 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 uzyskać pełne odniesienie 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 projekcyjne umożliwiają deweloperom zwracanie tylko tych właściwości, które ich interesują. Aby na przykład pobrać czas ostatniego działania wraz z identyfikatorem wszystkich urządzeń włączonych, ale niepołączonych, 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źniaków modułów

Wykonywanie zapytań dotyczących bliźniaczych reprezentacji modułu jest podobne do wykonywania zapytań dotyczących bliźniaczych reprezentacji urządzeń, ale używa się innej kolekcji/przestrzeni nazw; zamiast z urządzeń, zapytuje się z urządzenia.module:

SELECT * FROM devices.modules

Nie zezwalamy na łączenie kolekcji devices z devices.modules. Jeśli chcesz wykonywać zapytania dotyczące bliźniaczych modułów na różnych urządzeniach, można to zrobić na podstawie tagów. Następujące zapytanie zwraca wszystkie bliźniacze moduły na wszystkich urządzeniach, które mają stan skanowania:

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

Następujące zapytanie zwraca wszystkie duplikaty modułów ze statusem 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

Ważne

Wyniki zapytania są operacjami ostatecznie spójnymi i opóźnienia do 30 minut powinny być tolerowane. W większości przypadków zapytanie typu twin 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. Można korzystać z interfejsu API REST bezpośrednio lub użyć równoważnej funkcjonalności w jednym z zestawów SDK dla 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 w żadnym scenariuszu nie uzależniać się od właściwości lastActivityTime znalezionej w Właściwościach tożsamości urządzenia przy zapytaniach dotyczących bliźniaczych reprezentacji. 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 usługi IoT Hub w rozwiązaniu można znaleźć w temacie React to IoT Hub events by using Event Grid to trigger actions (Reagowanie na zdarzenia usługi IoT Hub 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 Latency Solutions.

Następne kroki