Sdílet prostřednictvím

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

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

Tady je ukázkové dvojče zařízení IoT hubu (dvojče modulu by bylo podobné, pouze by mělo parametr 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 týkající se digitálních dvojčat zařízení

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

SELECT * FROM devices

Poznámka:

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á celkový počet zařízení v IoT hubu:

SELECT COUNT() as totalNumberOfDevices FROM devices

Výsledky dotazu můžete filtrovat pomocí klauzule WHERE. Pokud například chcete 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áření složitých klauzulí 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 konfigurovaná tak, aby odesílala telemetrii 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í konkrétní vlastnost. IoT Hub podporuje funkci is_defined() pro tento účel. Následující dotaz například 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 .

Seskupování je také podporováno. 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 dotaz seskupení 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í hlásila úspěšnou konfiguraci, dvě stále používají konfiguraci a jedna nahlásila chybu.

Dotazy projekce umožňují vývojářům vracet pouze vlastnosti, o které se 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čete modulu

Dotazování na dvojčata modulů se podobá dotazování na dvojčata zařízení, ale používá se jiná kolekce nebo obor názvů; namísto dotazování ze zařízení se dotazuje z zařízení.moduly:

SELECT * FROM devices.modules

Nepovolujeme spojení mezi zařízeními a kolekcemi devices.modules. Pokud chcete dotazovat modulová dvojčata v rámci zařízení, uděláte to na základě značek. Následující dotaz vrátí všechny moduly dvojčat na všech zařízeních se stavem skenování:

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

Následující dotaz vrátí všechny instance modulů se stavem skenování, ale pouze na zadané podmnožině zařízení:

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

Omezení párových dotazů

Důležité

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

Alternativou k dotazům dvojčete je dotazování jednotlivých dvojčat zařízení pomocí 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 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.

Pro jakýkoli scénář doporučujeme nezabírat závislost na lastActivityTime nalezených ve vlastnostech identity zařízení pro dotazy dvojčete. 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 a aktivit zařízení. Další informace o používání událostí životního cyklu služby IoT Hub ve vašem řešení najdete v tématu Reakce na události služby IoT Hub 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

  • Last updated on