IoT Hub querytaal voor apparaat- en moduledubbels, taken en berichtroutering

IoT Hub biedt een krachtige SQL-achtige taal voor het ophalen van informatie over apparaat-tweelingen, module-tweelingen, taken en berichtroutering. In dit artikel wordt het volgende beschreven:

• Een inleiding tot de belangrijkste functies van de IoT Hub querytaal.
• Een gedetailleerde beschrijving van de taal. Zie IoT Hub querysyntaxis voor berichtroutering voor meer informatie over querytaal voor berichtroutering.

Zie Queries voor IoT Hub apparaat- en moduledubbels of Queries voor IoT Hub taken voor specifieke voorbeelden.

IoT Hub-query's uitvoeren

U kunt query's uitvoeren op uw IoT-hub rechtstreeks in Azure Portal.

1. Meld u aan bij de Azure-portal en ga naar uw IoT Hub.
2. Selecteer Query's in de sectie Apparaatbeheer van het navigatiemenu.
3. Voer uw query in het tekstvak in en selecteer Query uitvoeren.

U kunt ook query's in uw toepassingen uitvoeren met behulp van de SDK's en service-API's van de Azure IoT-service.

Zie de queryvoorbeelden met de service-SDK's sectie voor voorbeeldcode voor het implementeren van IoT Hub-query's.

Zie Azure IoT Hub SDK's voor koppelingen naar SDK-referentiepagina's en voorbeelden.

Basisbeginselen van een IoT Hub-query

Elke IoT Hub-query bestaat uit SELECT- en FROM-componenten, met optionele WHERE- en GROUP BY-componenten.

Query's worden uitgevoerd op een verzameling JSON-documenten, bijvoorbeeld digitale tweelingen van apparaten. De FROM-clause geeft de documentverzameling aan waarop moet worden geïtereerd (apparaten, devices.modules of devices.jobs).

Vervolgens wordt het filter in de WHERE-component toegepast. Met aggregaties worden de resultaten van deze stap gegroepeerd zoals opgegeven in de GROUP BY-component. Voor elke groep wordt een rij gegenereerd zoals opgegeven in de SELECT-component.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

SELECT-clausule

De SELECT <select_list> clausule is vereist in elke IoT Hub query. Hiermee geeft u op welke waarden uit de query worden opgehaald. Hiermee geeft u de JSON-waarden op die moeten worden gebruikt voor het genereren van nieuwe JSON-objecten. Voor elk element van de gefilterde (en optioneel gegroepeerde) subset van de FROM-verzameling genereert de projectiefase een nieuw JSON-object. Dit object wordt samengesteld met de waarden die zijn opgegeven in de SELECT-component.

Voorbeeld:

• Alle waarden retourneren

  SELECT *
  

• Specifieke eigenschappen retourneren

  SELECT DeviceID, LastActivityTime
  

• De resultaten van een query aggregeren om een telling te retourneren

  SELECT COUNT() as TotalNumber
  

Op dit moment worden selectiecomponenten die afwijken van SELECT alleen ondersteund in statistische query's op apparaatdubbels.

De volgende syntaxis is de grammatica van de SELECT-component:

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
    '*'
    | <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
    attribute_name
    | <projection_element> '.' attribute_name
    | <aggregate>

<aggregate> :==
    count()
    | avg(<projection_element>)
    | sum(<projection_element>)
    | min(<projection_element>)
    | max(<projection_element>)

Attribute_name verwijst naar een eigenschap van het JSON-document in de FROM-verzameling.

FROM-clausule

De FROM <from_specification> component is vereist in elke IoT Hub-query. Dit moet een van de volgende drie waarden zijn:

• apparaten om een query uit te voeren op apparaatdubbels
• devices.modules om query's uit te voeren op moduledubbels
• devices.jobs om de taakgegevens per apparaat op te vragen

Voorbeeld:

• Alle apparaat-tweelingen ophalen

  SELECT * FROM devices
  

WHERE-clausule

De WHERE <filter_condition> clausule is optioneel. Hiermee geeft u een of meer voorwaarden op waaraan de JSON-documenten in de FROM-verzameling moeten voldoen om als onderdeel van het resultaat te worden opgenomen. Ieder JSON-document moet de opgegeven voorwaarden evalueren om te bepalen of ze waar zijn om in het resultaat te worden opgenomen.

Voorbeeld:

• Alle taken ophalen die zijn gericht op een specifiek apparaat

  SELECT * FROM devices.jobs
    WHERE devices.jobs.deviceId = 'myDeviceId'
  

De toegestane voorwaarden worden beschreven in de sectie Expressies en voorwaarden .

GROUP BY-clausule

De GROUP BY <group_specification> clausule is optioneel. Deze component wordt uitgevoerd na het filter dat is opgegeven in de WHERE-component en vóór de projectie die is opgegeven in de SELECT. Documenten worden gegroepeerd op basis van de waarde van een kenmerk. Deze groepen worden gebruikt voor het genereren van geaggregeerde waarden zoals opgegeven in de SELECT-component.

Voorbeeld:

• Het aantal apparaten retourneren dat elke telemetrieconfiguratiestatus rapporteert

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

Momenteel wordt de GROUP BY-clause alleen ondersteund bij query's op device twins.

De formele syntaxis voor GROUP BY is:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name verwijst naar een eigenschap van het JSON-document in de FROM-verzameling.

Paginering van queryresultaten

Een queryobject wordt geïnstantieerd met een maximale paginagrootte van minder dan of gelijk aan 100 records. Als u meerdere pagina's wilt verkrijgen, roept u meerdere keren de methode nextAsTwin aan binnen de Node.js SDK of de methode GetNextAsTwinAsync binnen de .NET SDK. Een queryobject kan meerdere volgende waarden weergeven, afhankelijk van de deserialisatieoptie die is vereist voor de query. Een queryobject kan bijvoorbeeld apparaatdubbel- of taakobjecten retourneren, of gewone JSON bij het gebruik van projecties.

Expressies en voorwaarden

Op hoog niveau, een expressie:

• Evalueert naar een exemplaar van een JSON-type (zoals Booleaanse waarde, getal, tekenreeks, matrix of object).
• Wordt gedefinieerd door gegevens te bewerken die afkomstig zijn van het JSON-document en constanten van het apparaat met behulp van ingebouwde operators en functies.

Voorwaarden zijn expressies die resulteren in een Booleaanse waarde. Elke constante die anders is dan Booleaanse waar , wordt beschouwd als onwaar. Deze regel omvat null, undefined, elk object of array-instantie, elke string, en de Booleaanse waarde false.

De syntaxis voor expressies is:

<expression> ::=
    <constant> |
    attribute_name |
    <function_call> |
    <expression> binary_operator <expression> |
    <create_array_expression> |
    '(' <expression> ')'

<function_call> ::=
    <function_name> '(' expression ')'

<constant> ::=
    <undefined_constant>
    | <null_constant>
    | <number_constant>
    | <string_constant>
    | <array_constant>

<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

Raadpleeg de volgende tabel om te begrijpen waar elk symbool in de syntaxis van de expressies voor staat:

Operators

De volgende operators worden ondersteund:

Functions

Bij het opvragen van twins en taken is de enige ondersteunde functie:

In routes-voorwaarden worden de volgende wiskundige functies ondersteund:

Binnen routes-omstandigheden worden de volgende typecontrole- en typeconversiefuncties ondersteund:

In routecondities worden de volgende tekenreeksfuncties ondersteund:

Queryvoorbeelden met de service-SDK's

C#-voorbeeld

De queryfunctionaliteit wordt weergegeven door de Azure IoT Hub service-SDK voor .NET in de klasse RegistryManager.

Hier volgt een voorbeeld van een eenvoudige query:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

Het queryobject wordt geïnstantieerd met de parameters die worden vermeld in de sectie Queryresultatenpaginering . Meerdere pagina's worden opgehaald door de GetNextAsTwinAsync methoden meerdere keren aan te roepen.

Node.js voorbeeld

De queryfunctionaliteit wordt weergegeven door de Azure IoT Hub service-SDK voor Node.js in het object Registry.

Hier volgt een voorbeeld van een eenvoudige query:

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

Het queryobject wordt geïnstantieerd met de parameters die worden vermeld in de sectie Queryresultatenpaginering . Meerdere pagina's worden opgehaald door de nextAsTwin methode meerdere keren aan te roepen.

Query's voor IoT Hub apparaat- en moduledubbels

Apparaatdubbels en moduledubbels kunnen willekeurige JSON-objecten bevatten als tags en eigenschappen. IoT Hub stelt u in staat een query uit te voeren op apparaat-twins en module-twins in één JSON-document met alle twininformatie.

Hier volgt een voorbeeld van een IoT Hub-apparaat-twin (module-twin is vergelijkbaar met alleen 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 apparaattweelingen

IoT Hub maakt de apparaatdubbels beschikbaar als een documentverzameling met de naam devices. 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 apparaattwins wilt ontvangen waarbij de location.region tag 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 matrixconstanten gebruiken met de IN operatoren 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 hiervoor de functie is_defined(). 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 gerapporteerd dat de configuratie geslaagd is, twee zijn nog steeds bezig met het toepassen van de configuratie, en één heeft een fout gemeld.

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 moduletweelingen

Query's op module twins zijn vergelijkbaar met query's op device twins, maar met een andere verzameling/naamruimte; in plaats van uit devices, voert u een query uit devices.modules.

SELECT * FROM devices.modules

We staan geen join toe tussen de collecties 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 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

Een alternatieve optie voor twin-query's is om query's uit te voeren op afzonderlijke apparaat-tweelingen op basis van 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 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, zoals te vinden in apparaatgegevenskenmerken voor 'twin queries', in welk scenario dan ook. Dit veld garandeert geen nauwkeurige weergave van de status van het apparaat. Gebruik in plaats daarvan gebeurtenissen voor de levenscyclus van IoT-apparaten om de status en activiteiten van het apparaat te beheren. Zie Reageer op IoT Hub-evenementen door Event Grid te gebruiken om acties te activeren voor meer informatie over het gebruik van IoT Hub levenscyclus evenementen in uw oplossing.

Queries voor IoT Hub opdrachten

Taken bieden een manier om bewerkingen uit te voeren op sets van apparaten. Elke apparaat-twin bevat de informatie van de taken die daarop gericht zijn in een verzameling genaamd taken. Met IoT Hub kunt u opdrachten opvragen als een enkel JSON-document dat alle tweelinggegevens bevat.

Hier volgt een voorbeeld van een IoT Hub-apparaatstweeling die deel uitmaakt van een taak genaamd myJobId:

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "tags": {
        ...
    },
    "properties": {
        ...
    },
    "jobs": [
        {
            "deviceId": "myDeviceId",
            "jobId": "myJobId",
            "jobType": "scheduleUpdateTwin",
            "status": "completed",
            "startTimeUtc": "2016-09-29T18:18:52.7418462",
            "endTimeUtc": "2016-09-29T18:20:52.7418462",
            "createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
            "lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
            "outcome": {
                "deviceMethodResponse": null
            }
        },
        ...
    ]
}

Op dit moment kan deze verzameling worden opgevraagd als devices.jobs in de querytaal van IoT Hub.

De volgende query retourneert bijvoorbeeld alle taken (verleden en gepland) die van invloed zijn op één apparaat:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

Houd er rekening mee dat deze query de apparaatspecifieke status (en mogelijk het directe methode-antwoord) biedt van elke geretourneerde taak.

Het is ook mogelijk om te filteren met willekeurige Booleaanse voorwaarden voor alle objecteigenschappen in de devices.jobs verzameling.

Met de volgende query worden bijvoorbeeld alle voltooide updatetaken voor apparaatdubbels opgehaald die zijn gemaakt na september 2016 voor een specifiek apparaat:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'
    AND devices.jobs.jobType = 'scheduleUpdateTwin'
    AND devices.jobs.status = 'completed'
    AND devices.jobs.createdTimeUtc > '2016-09-01'

U kunt ook de resultaten per apparaat van één taak ophalen.

SELECT * FROM devices.jobs
  WHERE devices.jobs.jobId = 'myJobId'

Beperkingen voor jobquery's

Query-expressies kunnen maximaal 8192 tekens lang zijn.

Momenteel ondersteunen query's op devices.jobs het volgende niet:

• Projecties zijn dus alleen SELECT * mogelijk.
• Voorwaarden die verwijzen naar de 'device twin' in aanvulling op de eigenschappen van de taak (zie de vorige sectie).
• Aggregaties, zoals count, avg en group by.

Verwante inhoud

• Kom meer te weten over het routeren van berichten op basis van berichteigenschappen of berichtinhoud met de syntaxis van de IoT Hub-berichtrouteringsquery.