Query's voor IoT Hub apparaat en moduledubbels

  • Artikel

Apparaatdubbels en moduledubbels kunnen willekeurige JSON-objecten bevatten als zowel tags als eigenschappen. IoT Hub stelt u in staat om apparaatdubbels en moduledubbels op te vragen als één JSON-document met alle dubbelgegevens.

Hier volgt een voorbeeld van een IoT Hub-apparaatdubbel (moduledubbel is vergelijkbaar 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
        }
    }
}

Query's voor apparaatdubbels

IoT Hub worden de apparaatdubbels weergegeven als een documentverzameling met de naam apparaten. Met de meest eenvoudige query wordt bijvoorbeeld de hele set apparaatdubbels opgehaald:

SELECT * FROM devices

Notitie

Azure IoT SDK's ondersteunen paging van grote resultaten.

U kunt de resultaten van een query samenvoegen 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

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

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

Maak complexe WHERE-componenten met behulp van Booleaanse operatoren en rekenkundige vergelijkingen. Met de volgende query worden bijvoorbeeld apparaatdubbels opgehaald die zich in de VS bevinden en zijn geconfigureerd om telemetriegegevens minder dan elke minuut te verzenden:

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

U kunt ook matrixconstanten gebruiken met de operators IN en NIN (niet in). Met de volgende query worden bijvoorbeeld apparaatdubbels opgehaald die wi-fi- 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 doeleinde. 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 het volledige overzicht van de filtermogelijkheden.

Groeperen 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, twee zijn de configuratie nog steeds aan het toepassen en één heeft een fout gerapporteerd.

Met projectiequery's kunnen ontwikkelaars alleen de eigenschappen retourneren waar ze om geven. Als u bijvoorbeeld de tijd van de laatste activiteit wilt ophalen, samen met de apparaat-id van alle ingeschakelde apparaten die zijn losgekoppeld, 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"
  }
]

Moduledubbelquery's

Het uitvoeren van query's op moduledubbels is vergelijkbaar met het uitvoeren van query's op apparaatdubbels, maar het gebruik van een andere verzameling/naamruimte; in plaats van vanaf apparaten, kunt u query's uitvoeren vanaf devices.modules:

SELECT * FROM devices.modules

Koppeling tussen de verzamelingen apparaten en devices.modules is niet toegestaan. Als u een query 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 moduledubbels met de scanstatus, maar alleen op de opgegeven subset van apparaten:

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

Beperkingen voor dubbelquery's

Belangrijk

Queryresultaten zijn uiteindelijk consistente bewerkingen en vertragingen van maximaal 30 minuten moeten worden getolereerd. In de meeste gevallen retourneert dubbelquery resultaten in de orde van enkele seconden. IoT Hub streeft naar een lage latentie voor alle bewerkingen. Vanwege netwerkomstandigheden en andere onvoorspelbare factoren kan dit echter geen bepaalde latentie garanderen.

Een alternatieve optie voor dubbelquery's is het opvragen van afzonderlijke apparaatdubbels op id 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 sdk's van Azure IoT Hub Service.

Query-expressies mogen 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.

Het is raadzaam om geen afhankelijkheid te nemen van lastActivityTime die te vinden is in Eigenschappen van apparaatidentiteit voor dubbelquery's voor elk scenario. Dit veld garandeert geen nauwkeurige meter van de apparaatstatus. Gebruik in plaats daarvan levenscyclus-gebeurtenissen van IoT-apparaten om de status en activiteiten van apparaten te beheren. Voor meer informatie over het gebruik van IoT Hub levenscyclusgebeurtenissen in uw oplossing gaat u naar React om gebeurtenissen te IoT Hub met behulp van Event Grid om acties te activeren.

Notitie

Vermijd veronderstellingen over de maximale latentie van deze bewerking. Raadpleeg Latentieoplossingen voor meer informatie over het bouwen van uw oplossing, rekening houdend met latentie.

Volgende stappen