Langage de requête IoT Hub pour les jumeaux d’appareil et de module, les travaux et le routage des messages

IoT Hub fournit un puissant langage de type SQL pour récupérer des informations concernant les jumeaux d’appareil, les jumeaux de module, les travaux et le routage de messages. Cet article présente les éléments suivants :

• Présentation des principales fonctionnalités du langage de requête IoT Hub.
• Description détaillée de la langue. Pour plus d’informations sur le langage de requête pour le routage des messages, consultez la syntaxe de requête de routage des messages IoT Hub.

Pour obtenir des exemples spécifiques, consultez Requêtes pour les jumeaux de module et d’appareil IoT Hub ou Requêtes pour les tâches IoT Hub.

Exécuter des requêtes IoT Hub

Vous pouvez exécuter des requêtes sur votre hub IoT directement dans le portail Azure.

1. Connectez-vous au portail Azure et accédez à votre IoT Hub.
2. Sélectionnez Requêtes dans la section Gestion des appareils du menu de navigation.
3. Entrez votre requête dans la zone de texte, puis sélectionnez Exécuter la requête.

Vous pouvez également exécuter des requêtes au sein de vos applications à l’aide du kit Azure IoT service SDK et des API de service.

Pour du code exemple implémentant des requêtes IoT Hub, consultez la section Exemples de requêtes avec les SDKs de service.

Pour obtenir des liens vers des pages de référence et des exemples du Kit de développement logiciel (SDK), consultez les kits SDK Azure IoT Hub.

Principes de base d’une requête IoT Hub

Chaque requête IoT Hub se compose de clauses SELECT et FROM, avec des clauses WHERE et GROUP BY facultatives.

Les requêtes sont exécutées sur un jeu de données de documents JSON, par exemple des jumeaux d’appareil. La clause FROM indique le regroupement de documents sur lequel elle doit être itérée (devices, devices.modules ou devices.jobs).

Ensuite, le filtre dans la clause WHERE est appliqué. Avec des agrégations, les résultats de cette étape sont regroupés tel que spécifié dans la clause GROUP BY. Pour chaque groupe, une ligne est générée tel que spécifié dans la clause SELECT.

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

La clause SELECT

La clause SELECT <select_list> est requise dans chaque requête IoT Hub. Elle spécifie les valeurs qui sont récupérées de la requête. Elle spécifie les valeurs JSON à utiliser pour générer de nouveaux objets JSON. Pour chaque élément du sous-ensemble filtré (et éventuellement groupé) du regroupement FROM, la phase de projection génère un nouvel objet JSON. Cet objet est construit avec les valeurs spécifiées dans la clause SELECT.

Par exemple :

• Retourner toutes les valeurs

  SELECT *
  

• Retourner des propriétés spécifiques

  SELECT DeviceID, LastActivityTime
  

• Agréger les résultats d’une requête pour retourner un nombre

  SELECT COUNT() as TotalNumber
  

Actuellement, les clauses de sélection autres que SELECT ne sont prises en charge que dans les requêtes agrégées sur les gémellités d’appareils.

La grammaire de la clause SELECT est la suivante :

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 fait référence à n’importe quelle propriété du document JSON dans la collection FROM.

Clause FROM

La FROM <from_specification> clause est requise dans chaque requête IoT Hub. Cela peut être l’une des trois valeurs suivantes :

• devices pour interroger des jumeaux d'appareil
• devices.modules pour interroger des jumeaux de module
• devices.jobs pour interroger les détails du travail par appareil

Par exemple :

• Récupérer tous les jumeaux d’appareil

  SELECT * FROM devices
  

WHERE (clause)

La WHERE <filter_condition> clause est facultative. Elle indique une ou plusieurs conditions que les documents JSON du regroupement FROM doivent remplir pour être inclus dans le résultat. Tout document JSON doit évaluer les conditions spécifiées sur true pour être inclus dans le résultat.

Par exemple :

• Récupérer tous les travaux qui ciblent un appareil spécifique

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

Les conditions autorisées sont décrites dans la section Expressions et conditions .

Clause GROUP BY

La GROUP BY <group_specification> clause est facultative. Cette clause s’exécute après le filtre spécifié dans la clause WHERE et avant la projection spécifiée dans la clause SELECT. Elle groupe des documents en fonction de la valeur d’un attribut. Ces groupes sont utilisés pour générer des valeurs agrégées comme spécifié dans la clause SELECT.

Par exemple :

• Retourner le nombre d’appareils qui signalent chaque état de configuration de télémétrie

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

Actuellement, la clause GROUP BY est prise en charge uniquement lors de l’interrogation de jumeaux d’appareil.

La syntaxe formelle de la clause GROUP BY est la suivante :

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

Attribute_name fait référence à n’importe quelle propriété du document JSON dans la collection FROM.

Pagination des résultats de la requête

Un objet de requête est instancié avec une taille de page maximale inférieure ou égale à 100 enregistrements. Pour obtenir plusieurs pages, appelez plusieurs fois nextAsTwin sur le SDK Node.js ou GetNextAsTwinAsync sur la méthode du SDK .NET. L’objet de requête peut exposer plusieurs valeurs Next, en fonction de l’option de désérialisation requise par la requête. Par exemple, un objet de requête peut retourner les objets d’une tâche ou d’un jumeau d’appareil, ou un JSON simple lors de l’utilisation de projections.

Expressions et conditions

À un niveau élevé, une expression :

• Évalue à une instance d'un type JSON (par exemple, booléen, nombre, chaîne, tableau ou objet).
• est définie en manipulant des données provenant du document JSON de l’appareil et des constantes à l’aide de fonctions et d’opérateurs intégrés.

Les Conditions sont des expressions qui correspondent à une valeur booléenne. Toute constante autre qu’une valeur booléenne true est considérée comme false. Cette règle inclut null, undefined, toute instance d’objet ou de tableau, toute chaîne et la valeur booléenne false.

La syntaxe des expressions est la suivante :

<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>]+ ']'

Pour comprendre ce que signifie chaque symbole dans la syntaxe des expressions, consultez le tableau suivant :

Opérateurs

Les opérateurs suivants sont pris en charge :

Fonctions

Lors des requêtes de jumeaux ou de tâches, la seule fonction prise en charge est :

Dans les conditions d’itinéraire, les fonctions mathématiques suivantes sont prises en charge :

Dans les conditions de routage, les fonctions de vérification et de conversion de type suivantes sont prises en charge :

Dans les conditions de routage, les fonctions de chaînes de caractères suivantes sont prises en charge :

Exemples de requête avec les SDK de service

Exemple en code C#

La fonctionnalité de requête est exposée par le SDK de service Azure IoT Hub pour .NET dans la classe RegistryManager.

Voici un exemple de requête simple :

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

L’objet de requête est instancié avec les paramètres mentionnés dans la section pagination des résultats de la requête. Plusieurs pages sont récupérées en appelant les GetNextAsTwinAsync méthodes plusieurs fois.

Exemple de Node.js

La fonctionnalité de requête est exposée par le SDK de service Azure IoT Hub pour Node.js dans l’objet Registry.

Voici un exemple de requête simple :

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

L’objet de requête est instancié avec les paramètres mentionnés dans la section pagination des résultats de la requête. Plusieurs pages sont récupérées en appelant la nextAsTwin méthode plusieurs fois.

Requêtes pour les jumeaux d’appareil et de module IoT Hub

Les jumeaux d’appareil et les jumeaux de module peuvent contenir des objets JSON arbitraires en tant que balises et propriétés. IoT Hub vous permet d’interroger des jumeaux d’appareil et des jumeaux de module en tant que document JSON unique contenant toutes les informations de jumeau.

Voici un exemple de double d’appareil IoT Hub (le double de module est similaire, avec simplement un paramètre de 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
        }
    }
}

Requêtes de jumeau numérique d’appareil

IoT Hub expose les jumeaux d’appareil sous la forme d’une collection de documents appelée devices. Par exemple, la requête la plus simple récupère l’ensemble des jumeaux numériques :

SELECT * FROM devices

Vous pouvez agréger les résultats d’une requête à l’aide de la clause SELECT. Par exemple, la requête suivante obtient le nombre total d’appareils dans un hub IoT :

SELECT COUNT() as totalNumberOfDevices FROM devices

Filtrez les résultats de requête à l’aide de la clause WHERE. Par exemple, pour recevoir des jumeaux d’appareil où la location.region balise est définie sur US , utilisez la requête suivante :

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

Créez des clauses WHERE complexes à l’aide d’opérateurs booléens et de comparaisons arithmétiques. Par exemple, la requête suivante récupère les jumeaux numériques d’appareil situés aux États-Unis et configurés pour envoyer des données de télémétrie à une fréquence inférieure à une minute.

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

Vous pouvez également utiliser des constantes de tableau avec les opérateurs IN et NIN (pas dans). Par exemple, la requête suivante récupère les jumeaux d’appareil qui signalent une connectivité Wi-Fi ou câblée :

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

Il est souvent nécessaire d’identifier tous les "device twins" qui contiennent une propriété spécifique. IoT Hub prend en charge la fonction is_defined() à cet effet. Par exemple, la requête suivante récupère les jumeaux d’appareil qui définissent la connectivity propriété :

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

Reportez-vous à la section clause WHERE pour obtenir la référence complète des fonctionnalités de filtrage.

Le regroupement est également pris en charge. Par exemple, la requête suivante retourne le nombre d’appareils dans chaque état de configuration de télémétrie :

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

Cette requête de regroupement retourne un résultat similaire à l’exemple suivant :

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

Dans cet exemple, trois appareils ont signalé une configuration réussie, deux sont toujours en cours d’application de la configuration et l’autre a signalé une erreur.

Les requêtes de projection permettent aux développeurs de n’renvoyer que les propriétés qui les intéressent. Par exemple, pour récupérer l'heure de la dernière activité accompagnée de l'identifiant d'appareil de tous les appareils activés mais déconnectés, utilisez la requête suivante :

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

Le résultat de cette requête ressemblerait à l’exemple suivant :

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

Requêtes de jumeau de module

L’interrogation sur les jumeaux de modules est similaire à l’interrogation sur les jumeaux d’appareils, mais en utilisant une autre collection/espace de noms ; au lieu de partir de devices, vous interrogez à partir de devices.modules:

SELECT * FROM devices.modules

Nous n'autorisons pas la jointure entre les collections d'appareils et de modules d'appareils. Si vous souhaitez interroger des jumeaux de module sur plusieurs appareils, vous le faites en fonction des balises. La requête suivante renvoie toutes les paires de modules sur tous les appareils avec le statut d'analyse :

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

La requête suivante retourne tous les jumeaux de module avec l’état d’analyse, mais uniquement sur le sous-ensemble spécifié d’appareils :

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

Limitations des requêtes de jumeau

Une autre option pour les requêtes de jumeau consiste à interroger des jumeaux d’appareil individuels par ID à l’aide de l’API REST get twin. Cette API retourne toujours les dernières valeurs et présente des limites de limitation plus élevées. Vous pouvez émettre directement l’API REST ou utiliser les fonctionnalités équivalentes dans l’un des sdk Azure IoT Hub Service.

Les expressions de requête peuvent avoir une longueur maximale de 8 192 caractères.

Actuellement, les comparaisons sont prises en charge uniquement entre les types primitifs (aucun objet), par exemple ... WHERE properties.desired.config = properties.reported.config n’est prise en charge que si ces propriétés ont des valeurs primitives.

Nous vous recommandons de ne pas utiliser de dépendance lastActivityTime dans les propriétés d’identité d’appareil pour les requêtes de jumeau pour n’importe quel scénario. Ce champ ne garantit pas une jauge précise de l’état de l’appareil. Utilisez plutôt des événements de cycle de vie des appareils IoT pour gérer l’état et les activités de l’appareil. Pour plus d'informations sur l'utilisation des événements de cycle de vie IoT Hub dans votre solution, consultez Réagir aux événements IoT Hub à l'aide d'Event Grid pour déclencher des actions.

Requêtes pour les tâches de l'IoT Hub

Les travaux permettent d’exécuter des opérations sur des ensembles d’appareils. Chaque jumeau numérique de l'appareil contient les informations des tâches qui lui sont destinées dans une collection appelée jobs. IoT Hub vous permet d’interroger des travaux en tant que document JSON unique contenant toutes les informations de jumeau.

Voici un exemple de jumeau d’appareil IoT Hub qui fait partie d’une tâche appelée 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
            }
        },
        ...
    ]
}

Actuellement, cette collection peut être interrogeable comme devices.jobs dans le langage de requête IoT Hub.

Par exemple, la requête suivante retourne tous les travaux (passés et planifiés) qui affectent un seul appareil :

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

Notez comment cette requête fournit l’état spécifique à l’appareil (et éventuellement la réponse de méthode directe) de chaque tâche retournée.

Il est également possible de filtrer avec des conditions booléennes arbitraires sur toutes les propriétés d’objet de la devices.jobs collection.

Par exemple, la requête suivante récupère tous les travaux exécutés de mise à jour du jumeau numérique de l’appareil qui ont été créés après le mois de septembre 2016 pour un appareil spécifique.

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'

Vous pouvez également récupérer les résultats par appareil pour une seule tâche.

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

Limitations des requêtes de travaux

Les expressions de requête peuvent avoir une longueur maximale de 8 192 caractères.

Actuellement, les requêtes sur devices.jobs ne prennent pas en charge :

• Les projections, par conséquent, sont possibles uniquement SELECT * .
• Conditions qui font référence au jumeau d’appareil en plus des propriétés de la tâche (voir la section précédente).
• Agrégations, telles que le nombre, la moyenne et le groupe par.

Contenu connexe

• En savoir plus sur le routage des messages en fonction des propriétés ou du corps des messages avec la syntaxe des requêtes de routage des messages IoT Hub.