IoT Hub query language for device and module twins, jobs, and message routing

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 en
• De gedetailleerde beschrijving van de taal. For more information about query language for message routing, see IoT Hub message routing query syntax.

For specific examples, see Queries for IoT Hub device and module twins or Queries for IoT Hub jobs.

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.

For links to SDK reference pages and samples, see Azure IoT Hub SDKs.

Basisbeginselen van een IoT Hub-query

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

Queries are run on a collection of JSON documents, for example device twins. The FROM clause indicates the document collection to be iterated on (either devices, devices.modules, or 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 clause

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
  

Currently, selection clauses different than SELECT are only supported in aggregate queries on device twins.

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 VERZAMELING FROM.

FROM clause

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

• devices to query device twins
• devices.modules to query module twins
• devices.jobs to query job per-device details

Voorbeeld:

• Retrieve all device twins

  SELECT * FROM devices
  

WHERE clause

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. Elk JSON-document moet worden geëvalueerd om te controleren of de opgegeven voorwaarden "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'
  

The allowed conditions are described in the Expressions and conditions section.

GROUP BY clause

The GROUP BY <group_specification> clause is optional. 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
  

Currently, the GROUP BY clause is only supported when querying 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 VERZAMELING FROM.

Paginering van queryresultaten

Een queryobject wordt geïnstantieerd met een maximale paginagrootte van minder dan of gelijk aan 100 records. To obtain multiple pages, call the nextAsTwin on Node.js SDK or GetNextAsTwinAsync on .NET SDK method multiple times. 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

When querying twins and jobs the only supported function is:

In routes-voorwaarden worden de volgende wiskundige functies ondersteund:

In routes conditions, the following type checking and casting functions are supported:

In routecondities worden de volgende tekenreeksfuncties ondersteund:

Queryvoorbeelden met de service-SDK's

C#-voorbeeld

The query functionality is exposed by the Azure IoT Hub service SDK for .NET in the RegistryManager class.

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

The query object is instantiated with the parameters mentioned in the Query results pagination section. Meerdere pagina's worden opgehaald door de GetNextAsTwinAsync-methoden meerdere keren aan te roepen.

Node.js voorbeeld

The query functionality is exposed by the Azure IoT Hub service SDK for Node.js in the Registry object.

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);

The query object is instantiated with the parameters mentioned in the Query results pagination section. Meerdere pagina's worden opgehaald door de volgendeAsTwin-methode meerdere keren aan te roepen.

Volgende stappen

• Kom meer te weten over het routeren van berichten op basis van berichteigenschappen of berichtinhoud met de syntaxis van de IoT Hub-berichtrouteringsquery.
• Get specific examples of Queries for IoT Hub device and module twins or Queries for IoT Hub jobs.