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 jumeau d’appareil IoT Hub (le jumeau de module est similaire juste avec un paramètre pour 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 en tant que collection de documents appelée appareils. Par exemple, la requête la plus simple récupère l’ensemble des jumeaux d’appareil :

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 balise location.region 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 d’appareil situés aux États-Unis et configurés pour envoyer des données de télémétrie inférieures à toutes les minutes :

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 jumeaux d’appareil 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 retourner uniquement les propriétés qu’ils s’intéressent. Par exemple, pour récupérer la dernière activité avec l’ID d’appareil de tous les appareils activés 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 des jumeaux de module est similaire à l’interrogation sur des jumeaux d’appareil, mais à l’aide d’une autre collection/espace de noms ; Au lieu d’appareils, vous interrogez à partir de devices.modules :

SELECT * FROM devices.modules

Nous n’autorisez pas la jointure entre les appareils et les collections devices.modules. Si vous souhaitez interroger des jumeaux de module sur plusieurs appareils, vous le faites en fonction des balises. La requête suivante retourne tous les jumeaux de module sur tous les appareils avec l’état 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 kits SDK du service Azure IoT Hub.

Les expressions de requête peuvent avoir une longueur maximale de 8192 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 les é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 React aux événements IoT Hub à l’aide d’Event Grid pour déclencher des actions.

Étapes suivantes

• Comprendre les principes de base du langage de requête IoT Hub