Query's voor IoT Hub-apparaat- en moduletweelingen

Apparaatdubbels en moduledubbels kunnen willekeurige JSON-objecten bevatten als tags en eigenschappen. Met IoT Hub kunt u query's uitvoeren op apparaatdubbels en moduledubbels als één JSON-document met alle dubbelgegevens.

Hier volgt een voorbeeld van een IoT Hub-apparaatdubbel (moduledubbel zou vergelijkbaar zijn met een parameter voor 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
        }
    }
}

Queries voor apparaat-tweelingen

IoT Hub maakt de apparaatdubbels beschikbaar als een documentverzameling genaamd apparaten. Met de meest eenvoudige query wordt bijvoorbeeld de hele set apparaatdubbels opgehaald:

SELECT * FROM devices

U kunt de resultaten van een query aggregeren met behulp van de SELECT-component. Met de volgende query wordt bijvoorbeeld het totale aantal apparaten in een IoT-hub geteld:

SELECT COUNT() as totalNumberOfDevices FROM devices

Queryresultaten filteren met behulp van de WHERE-component. Als u bijvoorbeeld apparaatdubbels wilt ontvangen waarbij de tag location.region is ingesteld op US , gebruikt u de volgende query:

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

Maak complexe WHERE-componenten met behulp van Booleaanse operators en rekenkundige vergelijkingen. Met de volgende query worden bijvoorbeeld apparaatdubbels opgehaald die zich in de VS bevinden en zo geconfigureerd dat telemetrie minder dan elke minuut wordt verzonden:

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

U kunt ook arrayconstanten gebruiken met de IN- en NIN-operatoren (niet in). Bijvoorbeeld, de volgende query haalt apparaatdubbels op die wifi- of bekabelde connectiviteit rapporteren:

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

Het is vaak nodig om alle apparaatdubbels te identificeren die een specifieke eigenschap bevatten. IoT Hub ondersteunt de functie is_defined() voor dit doel. Met de volgende query worden bijvoorbeeld apparaatdubbels opgehaald die de connectivity eigenschap definiëren:

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

Raadpleeg de sectie WHERE-component voor de volledige verwijzing naar de filtermogelijkheden.

Groepering wordt ook ondersteund. De volgende query retourneert bijvoorbeeld het aantal apparaten in elke telemetrieconfiguratiestatus:

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

Deze groeperingsquery retourneert een resultaat dat vergelijkbaar is met het volgende voorbeeld:

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

In dit voorbeeld hebben drie apparaten een geslaagde configuratie gerapporteerd, bij twee wordt de configuratie nog steeds toegepast, en één heeft een fout gerapporteerd.

Met projectiequery's kunnen ontwikkelaars alleen de gewenste eigenschappen retourneren. Als u bijvoorbeeld de laatste activiteitstijd wilt ophalen, samen met de apparaat-id van alle apparaten waarvoor de verbinding is verbroken, gebruikt u de volgende query:

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

Het resultaat van die query ziet eruit als in het volgende voorbeeld:

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

Queries voor module-tweelingen

Query's uitvoeren op moduletweelingen is vergelijkbaar met query's uitvoeren op apparatentweelingen, maar door gebruik te maken van een andere verzameling/naamruimte; in plaats van vanaf apparaten voert u een query uit op devices.modules:

SELECT * FROM devices.modules

Het is niet toegestaan om een join uit te voeren tussen de verzamelingen apparaten en devices.modules. Als u query's wilt uitvoeren op moduledubbels op verschillende apparaten, doet u dit op basis van tags. De volgende query retourneert alle moduledubbels op alle apparaten met de scanstatus:

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

De volgende query retourneert alle moduletweelingen met de scanstatus, maar slechts voor de opgegeven subset van apparaten.

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

Beperkingen voor dubbelquery's

Een alternatieve optie voor tweeling-queries is om individuele apparaattweelingen op ID te bevragen met behulp van de get twin REST API. Deze API retourneert altijd de meest recente waarden en heeft hogere beperkingslimieten. U kunt de REST API rechtstreeks uitgeven of de equivalente functionaliteit gebruiken in een van de Azure IoT Hub Service SDK's.

Query-expressies kunnen maximaal 8192 tekens lang zijn.

Op dit moment worden vergelijkingen alleen ondersteund tussen primitieve typen (geen objecten), bijvoorbeeld ... WHERE properties.desired.config = properties.reported.config alleen als deze eigenschappen primitieve waarden hebben.

U wordt aangeraden geen afhankelijkheid te nemen van lastActivityTime gevonden apparaat-id-eigenschappen voor dubbelquery's voor elk scenario. Dit veld garandeert geen betrouwbare indicator van de apparaatstatus. Gebruik in plaats daarvan gebeurtenissen voor de levenscyclus van IoT-apparaten om de status en activiteiten van het apparaat te beheren. Meer informatie over het gebruik van levenscyclusgebeurtenissen van IoT Hub in uw oplossing vindt u op React to IoT Hub-gebeurtenissen door Event Grid te gebruiken om acties te activeren.

Volgende stappen

• De basisbeginselen van de IoT Hub-querytaal begrijpen