Comment utiliser l’API REST IoT Central pour interroger des appareils

L’API REST IoT Central vous permet de développer des applications clientes qui s’intègrent à des applications IoT Central. Vous pouvez utiliser l’API REST pour interroger des appareils dans votre application IoT Central. Voici des exemples de la façon dont vous pouvez utiliser l’API REST de requête :

• Obtenez les 10 dernières valeurs de télémétrie signalées par un appareil.
• Recherchez tous les appareils en état d’erreur et dont le microprogramme est obsolète.
• Tendances de télémétrie des appareils, en moyenne dans des fenêtres de 10 minutes.
• Obtenez la version actuelle du microprogramme de tous vos appareils à thermostat.

Cet article décrit comment utiliser l’API /query pour interroger des appareils.

Un appareil peut regrouper les propriétés, les données de télémétrie et les commandes qu’il prend en charge dans des composants et modules.

Chaque appel d’API REST IoT Central nécessite un en-tête d’autorisation. Pour plus d’informations, consultez Comment authentifier et autoriser les appels d’API REST d’IoT Central.

Pour obtenir la documentation de référence sur l’API REST IoT Central, consultez Informations de référence sur l’API REST d’Azure IoT Central.

Pour savoir comment interroger des appareils à l’aide de l’interface utilisateur IoT Central, consultez Comment utiliser l’explorateur de données pour analyser les données de l’appareil.

Exécuter une requête

Utilisez la requête suivante pour exécuter une requête :

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

La requête se trouve dans le corps de la requête et ressemble à ce qui suit :

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

La valeur dtmi:eclipsethreadx:devkit:hlby5jgib2o dans la clause FROM est un ID de modèle d’appareil. Pour rechercher un ID de modèle d’appareil, accédez à la page Périphériques dans votre application IOT Central et pointez sur un appareil qui utilise le modèle. La carte comprend l’ID du modèle d’appareil :

La réponse comprend la télémétrie de plusieurs appareils qui partagent le même modèle d’appareil. La réponse à cette demande ressemble à l’exemple suivant :

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Syntaxe

La syntaxe de requête est semblable à la syntaxe SQL, et est constituée des clauses suivantes :

• SELECT est obligatoire et définit les données que vous souhaitez récupérer, telles que les valeurs de télémétrie de l’appareil.
• FROM est obligatoire et identifie le type de périphérique que vous interrogez. Cette clause spécifie l’ID du modèle d’appareil.
• WHERE est facultatif et vous permet de filtrer les résultats.
• ORDER BY est facultatif et vous permet de trier les résultats.
• GROUP BY est facultatif et vous permet d’agréger les résultats.

Les sections suivantes décrivent ces clauses de façon plus détaillée.

Clause SELECT

La clause SELECT répertorie les valeurs de données à inclure dans le résultat de la requête et peut inclure les éléments suivants :

• Données de télémétrie. Utilisez les noms de télémétrie du modèle d’appareil.
• $id. L’ID de l’appareil.
• $provisioned. Valeur booléenne qui indique si l’appareil est déjà approvisionné.
• $simulated. Valeur booléenne qui indique si l’appareil est un appareil simulé.
• $ts. Timestamp associé à une valeur de télémétrie.

Si votre modèle d’appareil utilise des composants, vous référencez alors les données de télémétrie définies dans le composant comme suit :

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Le nom du composant se trouve dans le modèle d’appareil :

Les limites suivantes s’appliquent à la clause SELECT :

• Il n’y a pas d’opérateur générique.
• Vous ne pouvez pas avoir plus de 15 éléments dans la liste de sélection.
• Une requête retourne un maximum de 10 000 enregistrements.

Alias

Utilisez le mot clé AS afin de définir un alias pour un élément dans la clause SELECT. L’alias est utilisé dans le résultat de la requête. Vous pouvez également l’utiliser ailleurs dans la requête. Par exemple :

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Le résultat ressemble à la sortie suivante :

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

Utilisez TOP pour limiter le nombre de résultats retournées par la requête. Par exemple, la requête suivante renvoie les 10 premiers résultats :

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Si vous n’utilisez pas TOP, la requête retourne un maximum de 10 000 résultats.

Pour trier les résultats avant que TOP ne limite le nombre de résultats, utilisez l’option TRIER PAR.

Clause FROM

La clause FROM doit contenir un ID de modèle d’appareil. La clause FROM spécifie le type d’appareil que vous interrogez.

Pour rechercher un ID de modèle d’appareil, accédez à la page Périphériques dans votre application IOT Central et pointez sur un appareil qui utilise le modèle. La carte comprend l’ID du modèle d’appareil :

Vous pouvez également utiliser l’appel d’API REST Appareils - Get pour obtenir l’ID de modèle d’appareil d’un appareil.

Clause WHERE

La clause WHERE vous permet d’utiliser des valeurs et des fenêtres de temps pour filtrer les résultats :

Fenêtres Délai

Pour obtenir les données de télémétrie reçues par votre application dans une fenêtre de temps spécifiée, utilisez WITHIN_WINDOW dans le cadre de la clause WHERE. Par exemple, pour récupérer les données de télémétrie concernant la température et l’humidité du dernier jour, utilisez la requête suivante :

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

La valeur de la fenêtre de temps utilise le format de durée ISO 8601. Le tableau suivant présente quelques exemples :

Comparaisons de valeurs

Vous pouvez récupérer des données de télémétrie en fonction de valeurs spécifiques. Par exemple, la requête suivante retourne tous les messages dans lesquels la température est supérieure à zéro, la pression supérieure à 50 et l’ID d’appareil correspond à sample-002 ou sample-003 :

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

Les opérateurs suivants sont pris en charge :

• Opérateurs logiques AND et OR.
• Opérateurs de comparaison : =, !=, >, <, >=, <=, <> et IN.

Les limites suivantes s’appliquent à la clause WHERE :

• Vous pouvez utiliser un maximum de 10 opérateurs dans une même requête.
• Dans une requête, la clause WHERE ne peut contenir que des filtres de données de télémétrie et de métadonnées d’appareil.
• Dans une requête, vous pouvez récupérer jusqu’à 10 000 enregistrements.

Agrégations et clause TRIER PAR

Les fonctions d’agrégation vous permettent de calculer des valeurs telles que la moyenne, la valeur maximale et la valeur minimale des données de télémétrie dans une fenêtre de temps. Par exemple, la requête suivante calcule la température et l’humidité moyennes à partir de l’appareil sample-001 dans une fenêtre de 10 minutes :

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

Les résultats sont semblables à la sortie suivante :

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

Les fonctions d’agrégation suivantes sont prises en charge : SUM, MAX, MIN, COUNT, AVG, FIRST et LAST.

Utilisez GROUP BY WINDOW pour spécifier la taille de la fenêtre. Si vous n’utilisez pas GROUP BY WINDOW, la requête agrège les données de télémétrie des 30 derniers jours.

Clause ORDER BY

La clause ORDER BY vous permet de trier les résultats de la requête à l’aide d’une valeur de télémétrie, d’un timestamp ou de l’ID de l’appareil. Vous pouvez trier par ordre croissant ou décroissant. Par exemple, la requête suivante renvoie les résultats les plus récents en premier :

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

Limites

Les limites actuelles pour les requêtes sont les suivantes :

• Pas plus de 15 éléments dans la liste des clauses SELECT.
• Pas plus de 10 opérations logiques dans la clause WHERE.
• La longueur maximale de la chaîne de requête est de 350 caractères.
• Vous ne pouvez pas utiliser le caractère générique (*) dans la liste des clauses SELECT.
• Les requêtes peuvent récupérer jusqu’à 10 000 enregistrements.

Étapes suivantes

Maintenant que vous savez comment interroger les appareils avec l’API REST, nous vous suggérons d’apprendre à utiliser l’API REST IoT Central pour gérer les utilisateurs et les rôles.