Dotazy na dvojčata IoT Hub zařízení a modulů

  • Článek

Dvojčata zařízení a dvojčata modulů můžou obsahovat libovolné objekty JSON jako značky i vlastnosti. IoT Hub umožňuje dotazovat se na dvojčata zařízení a dvojčata modulů jako jeden dokument JSON obsahující všechny informace o dvojčatech.

Tady je ukázka dvojčete zařízení služby IoT Hub (dvojče modulu by bylo podobné jenom s 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
        }
    }
}

Dotazy dvojčat zařízení

IoT Hub zpřístupňuje dvojčata zařízení jako kolekci dokumentů s názvem zařízení. Například nejzákladnější dotaz načte celou sadu dvojčat zařízení:

SELECT * FROM devices

Poznámka

Sady Azure IoT SDK podporují stránkování velkých výsledků.

Výsledky dotazu můžete agregovat pomocí klauzule SELECT. Následující dotaz například získá počet celkového počtu zařízení ve službě IoT Hub:

SELECT COUNT() as totalNumberOfDevices FROM devices

Výsledky dotazu můžete filtrovat pomocí klauzule WHERE. Pokud chcete například přijímat dvojčata zařízení, kde je značka location.region nastavená na USA , použijte následující dotaz:

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

Vytvářejte složité klauzule WHERE pomocí logických operátorů a aritmetických porovnání. Následující dotaz například načte dvojčata zařízení umístěná v USA a nakonfigurovaná tak, aby odesílala telemetrická data méně než každou minutu:

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

Můžete také použít maticové konstanty s operátory IN a NIN (ne in). Následující dotaz například načte dvojčata zařízení, která hlásí připojení Wi-Fi nebo kabelové připojení:

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

Často je potřeba identifikovat všechna dvojčata zařízení, která obsahují určitou vlastnost. IoT Hub podporuje funkci is_defined() pro tento účel. Například následující dotaz načte dvojčata zařízení, která definují connectivity vlastnost:

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

Úplný odkaz na možnosti filtrování najdete v části KLAUZULE WHERE .

Podporuje se také seskupení. Například následující dotaz vrátí počet zařízení v každém stavu konfigurace telemetrie:

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

Tento seskupovací dotaz by vrátil výsledek podobný následujícímu příkladu:

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

V tomto příkladu tři zařízení nahlásila úspěšnou konfiguraci, dvě stále používají konfiguraci a jedno nahlásilo chybu.

Dotazy projekce umožňují vývojářům vracet pouze vlastnosti, které je zajímají. Pokud například chcete načíst čas poslední aktivity spolu s ID zařízení všech povolených zařízení, která jsou odpojená, použijte následující dotaz:

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

Výsledek tohoto dotazu by vypadal jako v následujícím příkladu:

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

Dotazy dvojčat modulů

Dotazování na dvojčata modulů se podobá dotazování na dvojčata zařízení, ale používá jinou kolekci nebo obor názvů. místo ze zařízení se dotazujete z devices.modules:

SELECT * FROM devices.modules

Nepovolujeme spojení mezi kolekcemi devices a devices.modules. Pokud chcete dotazovat dvojčata modulů napříč zařízeními, provedete to na základě značek. Následující dotaz vrátí všechna dvojčata modulů na všech zařízeních se stavem kontroly:

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

Následující dotaz vrátí všechna dvojčata modulu se stavem kontroly, ale pouze na zadané podmnožině zařízení:

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

Omezení dotazů dvojčat

Důležité

Výsledky dotazu jsou nakonec konzistentní operace a zpoždění až 30 minut by mělo být tolerováno. Ve většině případů vrací dotaz dvojčete výsledky v řádu několika sekund. IoT Hub se snaží zajistit nízkou latenci pro všechny operace. Kvůli podmínkám sítě a dalším nepředvídatelným faktorům však nemůže zaručit určitou latenci.

Alternativou k dotazům dvojčat je dotazování jednotlivých dvojčat zařízení podle ID pomocí rozhraní REST API get twin. Toto rozhraní API vždy vrací nejnovější hodnoty a má vyšší limity omezování. Rozhraní REST API můžete vydat přímo nebo můžete použít ekvivalentní funkce v některé ze sad SDK služby Azure IoT Hub.

Výrazy dotazu můžou mít maximální délku 8192 znaků.

V současné době jsou porovnání podporována pouze mezi primitivními typy (bez objektů), například ... WHERE properties.desired.config = properties.reported.config je podporována pouze v případě, že tyto vlastnosti mají primitivní hodnoty.

V žádném scénáři doporučujeme nebrat závislost na lastActivityTime ve vlastnostech identity zařízení pro dotazy dvojčat. Toto pole nezaručuje přesné měřidlo stavu zařízení. Místo toho použijte události životního cyklu zařízení IoT ke správě stavu zařízení a aktivit. Další informace o používání událostí životního cyklu IoT Hub ve vašem řešení najdete v tématu React, kde můžete IoT Hub události pomocí služby Event Grid k aktivaci akcí.

Poznámka

Nepoužívejte žádné předpoklady týkající se maximální latence této operace. Další informace o tom, jak sestavit řešení s ohledem na latenci, najdete v tématu Řešení latence.

Další kroky