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 :
- Une introduction aux principales fonctionnalités du langage de requête d’IoT Hub
- Une description détaillée du langage Pour plus d’informations sur le langage de requête pour le routage des messages, consultez Requêtes dans le routage des messages.
Pour obtenir des exemples spécifiques, consultez Requêtes pour les jumeaux de module et d’appareil ou Requêtes pour les travaux.
Notes
Certaines des fonctionnalités mentionnées dans cet article, comme la messagerie cloud-à-appareil, les jumeaux d’appareil et la gestion des appareils, sont disponibles uniquement dans le niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.
Exécuter des requêtes IoT Hub
Vous pouvez exécuter des requêtes sur votre hub IoT directement dans le portail Azure.
- Connectez-vous au portail Azure et accédez à votre IoT Hub.
- Sélectionnez Requêtes dans la section Gestion des appareils du menu de navigation.
- 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.
Par du code exemple implémentant des requêtes IoT Hub, consultez la section Exemples de requête avec le kit SDK du service.
Pour obtenir des liens vers des pages de référence et des exemples du SDK, consultez SDK Azure IoT.
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 regroupement 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>]
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, LastActivityTimeAgré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 sont prises en charge uniquement dans les requêtes d’agrégation sur des jumeaux d’appareil.
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 le regroupement FROM.
Clause FROM
La clause FROM <from_specification> 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 clause WHERE <filter_condition> est facultative. Elle indique une ou plusieurs conditions que les documents JSON du regroupement FROM doivent remplir pour être inclus dans le résultat. Pour être inclus dans le résultat, chaque document JSON doit évaluer les conditions spécifiées comme « true ».
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 clause GROUP BY <group_specification> 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.
Attention
Le terme group est actuellement traité comme un mot clé spécial dans les requêtes. Si vous utilisez group comme nom de propriété, vous pouvez l’encadrer entre doubles crochets pour éviter les erreurs, par exemple, SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.
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 le regroupement 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 la méthode nextAsTwin sur le kit de développement logiciel (SDK) Node.js ou GetNextAsTwinAsync sur le 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 de travail ou de jumeau d’appareil, ou le code JSON brut lors de l’utilisation de projections.
Expressions et conditions
À un niveau élevé, une expression :
- prend la valeur d’une instance d’un type JSON (par exemple, Boolean, number, string, array ou object) ;
- 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 :
| Symbole | Définition |
|---|---|
| attribute_name | Toute propriété du document JSON dans le regroupement FROM. |
| binary_operator | Tout opérateur binaire répertorié dans la section Operators. |
| function_name | Toutes les fonctions répertoriées dans la section Fonctions. |
| decimal_literal | Variable exprimée en notation décimale. |
| hexadecimal_literal | Nombre exprimé par la chaîne « 0x » suivie d’une chaîne de chiffres hexadécimaux. |
| string_literal | Des chaînes Unicode représentées par une séquence de zéro ou plusieurs caractères Unicode ou séquences d’échappement. Les littéraux de chaîne sont placés entre guillemets simples ou guillemets doubles. Échappements autorisés : \', \", \\, \uXXXX pour les caractères Unicode définis par quatre chiffres hexadécimaux. |
Opérateurs
Les opérateurs suivants sont pris en charge :
| Famille | Opérateurs |
|---|---|
| Arithmétique | +, -, *, /, % |
| Logical | AND, OR, NOT |
| Comparaison | =, !=, <, >, <=, >=, <> |
Fonctions
Lors des requêtes de jumeaux ou de travaux, la seule fonction prise en charge est :
| Fonction | Description |
|---|---|
| IS_DEFINED(property) | Retourne une valeur booléenne indiquant si une valeur a été attribuée à la propriété (dont null). |
Dans les conditions d’itinéraire, les fonctions mathématiques suivantes sont prises en charge :
| Fonction | Description |
|---|---|
| ABS(x) | Retourne la valeur (positive) absolue de l'expression numérique spécifiée. |
| EXP(x) | Retourne la valeur exponentielle de l'expression numérique spécifiée (e^x). |
| POWER(x,y) | Retourne la valeur de l’expression spécifiée élevée à la puissance spécifiée (x^y). |
| SQUARE(x) | Retourne le carré de la valeur numérique spécifiée. |
| CEILING(x) | Retourne le plus petit nombre entier qui est supérieur ou égal à l'expression numérique spécifiée. |
| FLOOR(x) | Renvoie le nombre entier le plus grand, inférieur ou égal à l'expression numérique donnée. |
| SIGN(x) | Retourne le signe positif (+1), nul (0) ou négatif (-1) de l'expression numérique spécifiée. |
| SQRT(x) | Retourne la racine carrée de la valeur numérique spécifiée. |
Dans les conditions d’itinéraire, les fonctions de vérification et de conversion de type suivantes sont prises en charge :
| Fonction | Description |
|---|---|
| AS_NUMBER | Convertit la chaîne d’entrée en nombre. noop si l’entrée est un nombre ; Undefined si la chaîne ne représente pas un nombre. |
| IS_ARRAY | Retourne une valeur booléenne indiquant si l’expression spécifiée est du type tableau. |
| IS_BOOL | Retourne une valeur booléenne indiquant si l’expression spécifiée est du type booléen. |
| IS_DEFINED | Retourne une valeur booléenne indiquant si une valeur a été attribuée à la propriété. Cette fonction est uniquement prise en charge lorsque la valeur est de type primitif. Exemples de types primitifs : chaîne, booléen, numérique ou null. DateHeure, les types d'objets et les tableaux ne sont pas pris en charge. |
| IS_NULL | Retourne une valeur booléenne indiquant si l’expression spécifiée est de type null. |
| IS_NUMBER | Retourne une valeur booléenne indiquant si l’expression spécifiée est du type nombre. |
| IS_OBJECT | Retourne une valeur booléenne indiquant si l’expression spécifiée est du type objet JSON. |
| IS_PRIMITIVE | Retourne une valeur booléenne indiquant si l’expression spécifiée est de type primitif (chaîne, booléen, numérique ou null). |
| IS_STRING | Retourne une valeur booléenne indiquant si l’expression spécifiée est du type chaîne. |
Dans les conditions d’itinéraire, les fonctions de chaîne suivantes sont prises en charge :
| Fonction | Description |
|---|---|
| CONCAT(x, y, …) | Retourne une chaîne qui est le résultat de la concaténation d’au moins deux valeurs de chaîne. |
| LENGTH(x) | Retourne le nombre de caractères de l’expression de chaîne spécifiée. |
| LOWER(x) | Retourne une expression de chaîne après la conversion des caractères majuscules en caractères minuscules. |
| UPPER(x) | Retourne une expression de chaîne après la conversion des caractères minuscules en caractères majuscules. |
| SUBSTRING(string, start [, length]) | Renvoie une partie d’une expression de chaîne commençant à la position de caractère spécifiée (avec base zéro) et se poursuit jusqu'à la longueur spécifiée ou à la fin de la chaîne. |
| INDEX_OF(string, fragment) | Retourne la position de départ de la première occurrence de la seconde expression de chaîne dans la première expression de chaîne spécifiée, ou -1 si la chaîne est introuvable. |
| STARTSWITH(x, y) | Retourne une valeur booléenne indiquant si la première expression de chaîne commence par la seconde. |
| ENDSWITH(x, y) | Retourne une valeur booléenne indiquant si la première expression de chaîne se termine par la seconde. |
| CONTAINS(x,y) | Retourne une valeur booléenne indiquant si la première expression de chaîne contient la seconde. |
Exemples de requête avec les SDK de service
Exemple en code C#
La fonctionnalité de requête est exposée par Service SDK C# 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 plusieurs fois les méthodes GetNextAsTwinAsync.
Exemple de Node.js
La fonctionnalité de requête est exposée par le Kit Azure IoT service SDK 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 plusieurs fois la méthode nextAsTwin.
Étapes suivantes
- 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.
- Obtenez des exemples spécifiques de Requêtes pour les jumeaux de module et d’appareil ou Requêtes pour les travaux.