Partager via

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

  • Article

Des jumeaux d’appareil et des jumeaux de module peuvent contenir des objets JSON arbitraires tels que des étiquettes et des propriétés. IoT Hub vous permet d’interroger des jumeaux d’appareil et des jumeaux de module sous la forme d’un seul document JSON contenant toutes les informations sur les jumeaux.

Voici un exemple de jumeau d’appareil IoT Hub (l’exemple serait similaire pour un jumeau de module 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 représentations 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 élémentaire permet de récupérer l’ensemble des jumeaux d’appareil :

SELECT * FROM devices

Notes

Les kits Azure IoT SDK prennent en charge la pagination des résultats volumineux.

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 la requête à l’aide de la clause WHERE. Par exemple, pour recevoir des jumeaux d’appareils dont 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 permet de retrouver les jumeaux d’appareils situés dans la région « US » et configurés pour envoyer la télémétrie à un intervalle supérieur à la minute :

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

Vous pouvez également utiliser les 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() à cette fin. Par exemple, la requête suivante récupère les jumeaux d’appareil qui définissent la propriété connectivity :

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

Pour une référence complète sur les fonctionnalités de filtrage, consultez la section clause WHERE.

Le regroupement est également pris en charge. Par exemple, la requête suivante renvoie 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 ci-dessous :

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

Dans cet exemple, trois appareils ont signalé une configuration réussie, deux appliquent toujours la configuration et un signale une erreur.

Les requêtes de projection permettent aux développeurs de retourner uniquement les propriétés qui les intéressent. Par exemple, pour récupérer l’heure de la dernière activité avec l’ID de tous les appareils activés et 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 ressemble à l’exemple suivant :

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

Requêtes de jumeaux de module

L’interrogation de jumeaux de module est similaire à l’interrogation de jumeaux d’appareil, à la différence que vous utilisez une collection/un espace de noms différent. En d’autres termes, au lieu d’utiliser devices, vous interrogez device.modules :

SELECT * FROM devices.modules

Nous n’autorisons pas de jointure entre les collections devices et devices.modules. Si vous voulez interroger les jumeaux de module sur les appareils, vous le faites sur la base des étiquettes. La requête suivante renvoie tous les jumeaux de modules sur tous les appareils avec l’état d’analyse :

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

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

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

Limites de la requête de jumeau

Important

Les résultats des requêtes sont finalement des opérations cohérentes et des retards allant jusqu’à 30 minutes doivent être tolérés. Dans la plupart des cas, une requête de jumeau retourne des résultats en quelques secondes. IoT Hub s’efforce de fournir une faible latence pour toutes les opérations. Toutefois, en raison des conditions réseau et d’autres facteurs imprévisibles, il ne peut pas garantir une latence spécifique.

Une autre option pour les requêtes de jumeau consiste à interroger des jumeaux d’appareil individuels par ID à l’aide de l’API REST d’obtention de jumeau. Cette API retourne toujours les valeurs les plus récentes et ses seuils de limitation sont plus élevés. Vous pouvez émettre l’API REST directement ou utiliser la fonctionnalité équivalente dans l’un des kits Azure IoT Hub Service SDK.

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

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

Nous vous recommandons de ne pas prendre de dépendance vis-à-vis de la valeur lastActivityTime trouvée dans les propriétés d’identité des appareils pour les requêtes de jumeau dans tous les scénarios. Ce champ ne garantit pas une jauge précise de l’état des appareils. Utilisez plutôt les événements du cycle de vie des appareils IoT pour gérer l’état et les activités des appareils. Pour plus d’informations sur la manière d’utiliser les événements du cycle de vie IoT Hub dans votre solution, consultez Réagir aux événements IoT Hub en utilisant Event Grid pour déclencher des actions.

Notes

Évitez de faire d’hypothèses concernant la latence maximale de cette opération. Pour plus d’informations sur la création de votre solution en tenant compte de la latence, consultez Solutions de latence.

Étapes suivantes