Share via

Lekérdezések IoT Hub ikereszközökhöz és modulokhoz

  • Cikk

Az ikereszközök és a modulikrek tetszőleges JSON-objektumokat tartalmazhatnak címkékként és tulajdonságokként is. IoT Hub lehetővé teszi az ikereszközök és modulikrek lekérdezését egyetlen, az összes ikeradatot tartalmazó JSON-dokumentumként.

Íme egy IoT Hub-ikereszköz-minta (a modul ikerpéldánya hasonló lenne a moduleId paraméteréhez):

{
    "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
        }
    }
}

Ikereszköz-lekérdezések

IoT Hub az ikereszközöket eszközök nevű dokumentumgyűjteményként teszi elérhetővé. A legalapvetőbb lekérdezés például lekéri az ikereszközök teljes készletét:

SELECT * FROM devices

Megjegyzés

Az Azure IoT SDK-k támogatják a nagy eredmények lapozását.

Egy lekérdezés eredményeit a SELECT záradékkal összesítheti. A következő lekérdezés például az IoT Hubban található eszközök teljes számát számítja ki:

SELECT COUNT() as totalNumberOfDevices FROM devices

Szűrje a lekérdezési eredményeket a WHERE záradékkal. Ha például olyan ikereszközöket szeretne fogadni, ahol a location.region címke us értékre van állítva, használja a következő lekérdezést:

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

Összetett WHERE záradékok létrehozása logikai operátorok és számtani összehasonlítások használatával. A következő lekérdezés például lekéri az USA-ban található ikereszközöket, és úgy van konfigurálva, hogy percenként kevesebb telemetriát küldjön:

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

Tömbállandókat az IN és az NIN (nem in) operátorokkal is használhat. A következő lekérdezés például lekéri azokat az ikereszközöket, amelyek Wi-Fi-t vagy vezetékes kapcsolatot jelentenek:

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

Gyakran szükséges azonosítani az összes olyan ikereszközt, amely egy adott tulajdonságot tartalmaz. IoT Hub támogatja a függvényt is_defined() erre a célra. A következő lekérdezés például lekéri a tulajdonságot meghatározó ikereszközöket connectivity :

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

A szűrési képességek teljes körű ismertetését a WHERE záradék szakaszában találja.

A csoportosítás is támogatott. A következő lekérdezés például az egyes telemetriai konfigurációs állapotokban lévő eszközök számát adja vissza:

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

Ez a csoportosítási lekérdezés az alábbi példához hasonló eredményt ad vissza:

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

Ebben a példában három eszköz jelentett sikeres konfigurációt, kettő továbbra is alkalmazza a konfigurációt, az egyik pedig hibát jelzett.

A leképezési lekérdezések lehetővé teszik a fejlesztők számára, hogy csak a számukra fontos tulajdonságokat adjanak vissza. Ha például le szeretné kérni az utolsó tevékenység időpontját és az összes leválasztott eszköz eszközazonosítóját, használja a következő lekérdezést:

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

A lekérdezés eredménye a következő példához hasonlóan fog kinézni:

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

Ikermodul-lekérdezések

Az ikermodulok lekérdezése hasonló az ikereszközökön végzett lekérdezésekhez, de más gyűjteményt/névteret használ; az eszközök helyett az devices.modules modulból kérdezi le:

SELECT * FROM devices.modules

Nem engedélyezzük az eszközök és az devices.modules gyűjtemények közötti csatlakozást. Ha több eszközön szeretné lekérdezni az ikermodulokat, azt címkék alapján kell elvégeznie. A következő lekérdezés az összes ikermodult visszaadja az összes eszközre a vizsgálati állapottal:

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

A következő lekérdezés az összes vizsgálati állapotú moduli ikerpéldányt visszaadja, de csak az eszközök megadott részhalmazán:

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

Az iker lekérdezés korlátozásai

Fontos

A lekérdezési eredmények végül konzisztens műveletek, és legfeljebb 30 perces késéseket kell tolerálni. A legtöbb esetben az iker lekérdezés néhány másodperces sorrendben adja vissza az eredményeket. IoT Hub arra törekszik, hogy minden művelet esetében alacsony késést biztosítson. A hálózati feltételek és más kiszámíthatatlan tényezők miatt azonban nem garantálható bizonyos késés.

Az iker lekérdezések másik lehetősége, ha az ikereszköz-ikereszközöket azonosító alapján kérdezi le a get twin REST API használatával. Ez az API mindig a legújabb értékeket adja vissza, és magasabb szabályozási korlátokkal rendelkezik. A REST API-t közvetlenül is kibocsáthatja, vagy használhatja az ezzel egyenértékű funkciókat az Azure IoT Hub Service SDK-k egyikében.

A lekérdezési kifejezések legfeljebb 8192 karakter hosszúságúak lehetnek.

Az összehasonlítások jelenleg csak primitív típusok (objektumok nélkül) támogatottak, például ... WHERE properties.desired.config = properties.reported.config csak akkor, ha ezek a tulajdonságok primitív értékekkel rendelkeznek.

Javasoljuk, hogy semmilyen forgatókönyv esetén ne függjön az iker lekérdezések eszközidentitás-tulajdonságai között található lastActivityTime-ról. Ez a mező nem garantálja az eszköz állapotának pontos mérőműszerét. Ehelyett használjon IoT-eszközéletciklus-eseményeket az eszköz állapotának és tevékenységeinek kezeléséhez. Az IoT Hub életciklus-események megoldásban való használatával kapcsolatos további információkért látogasson el a React webhelyre, ahol IoT Hub eseményeket az Event Grid használatával a műveletek aktiválásához.

Megjegyzés

Kerülje a művelet maximális késésére vonatkozó feltételezéseket. A késés figyelembevételével a megoldás felépítéséről további információt a Késési megoldások című témakörben talál.

Következő lépések