Share via

Comment utiliser l’API REST IoT Central pour contrôler les appareils

  • Article

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 contrôler les appareils dans votre application IoT Central. L’API REST vous permet de :

  • Lire la dernière valeur connue de télémétrie d’un appareil.
  • Lire les valeurs de propriété d’un appareil.
  • Définissez des propriétés accessibles en écriture sur un appareil.
  • Appeler des commandes sur un appareil.

Cet article explique comment utiliser l’API /devices/{device_id} pour contrôler des appareils individuels. Vous pouvez également utiliser des travaux pour contrôler les appareils en bloc.

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.

Conseil

Vous pouvez utiliser Postman pour tester les appels d’API REST décrits dans cet article. Téléchargez la collection IoT Central Postman et importez-la dans Postman. Dans la collection, vous devez définir des variables telles que votre sous-domaine d’application et le jeton d’administrateur.

Pour savoir comment contrôler les appareils à l’aide de l’interface utilisateur IoT Central, consultez

Composants et modules

Les composants vous permettent de regrouper et réutiliser les fonctionnalités des appareils. Pour en savoir plus sur les composants et les modèles d’appareil, consultez le Guide de modélisation d’IoT Plug-and-Play.

Tous les modèles d’appareil n’utilisent pas de composants. La capture d’écran suivante montre le modèle d’appareil pour un thermostat simple dans lequel toutes les fonctionnalités sont définies dans une interface unique appelée Composant racine :

Screenshot that shows a simple no component thermostat device.

La capture d’écran suivante montre un modèle d’appareil de contrôleur de température qui utilise des composants. Le contrôleur de température a deux composants de thermostat et un composant d’informations sur l’appareil :

Screenshot that shows a temperature controller device with two thermostat components and a device information component.

Dans IoT Central, un module fait référence à un module IoT Edge exécuté sur un appareil IoT Edge connecté. Un module peut avoir un modèle simple, tel que le thermostat qui n’utilise pas de composants. Un module peut également utiliser des composants pour organiser un ensemble plus complexe de fonctionnalités. La capture d’écran suivante montre un exemple de modèle d’appareil qui utilise des modules. Le périphérique capteur d’environnement a un module appelé SimulatedTemperatureSensor et une interface héritée appelée management :

Screenshot that shows an environmental sensor device with a module.

Obtenir un composant d’appareil

Utilisez la requête suivante pour récupérer les composants d’un appareil appelé temperature-controller-01 :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components?api-version=2022-07-31

La réponse à cette demande se présente comme dans l’exemple suivant. Le tableau value contient les détails de chaque composant d’appareil :

{
  "value": [
    {
      "@type": "Component",
      "name": "thermostat1",
      "displayName": "Thermostat One",
      "description": "Thermostat One of Two."
    },
    {
      "@type": "Component",
      "name": "thermostat2",
      "displayName": "Thermostat Two",
      "description": "Thermostat Two of Two."
    },
    {
      "@type": "Component",
      "name": "deviceInformation",
      "displayName": "Device Information interface",
      "description": "Optional interface with basic device hardware information."
    }
  ]
}

Obtenir un module d’appareil

Utilisez la requête suivante pour récupérer une liste de modules s’exécutant sur un appareil IoT Edge connecté, appelé environmental-sensor-01 :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

La réponse à cette demande se présente comme dans l’exemple suivant. Le tableau de modules comprend uniquement des modules personnalisés qui s’exécutent sur l’appareil IoT Edge, pas les modules intégrés $edgeAgent et $edgeHub :

{
  "value": [
    {
      "@type": [
        "Relationship",
        "EdgeModule"
      ],
      "name": "SimulatedTemperatureSensor",
      "displayName": "SimulatedTemperatureSensor"
    }
  ]
}

Utilisez la requête suivante pour récupérer une liste des composants dans un module appelé SimulatedTemperatureSensor :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

Lire les données de télémétrie

Utilisez la requête suivante pour récupérer la dernière valeur connue de télémétrie à partir d’un appareil qui n’utilise pas de composants. Dans cet exemple, l’appareil est appelé thermostat-01 et la télémétrie est appelée temperature :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/telemetry/temperature?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "timestamp": "2021-03-24T12:33:15.223Z",
  "value": 40.10993804456927
}

Utilisez la requête suivante pour récupérer la dernière valeur connue de télémétrie à partir d’un appareil qui utilise des composants. Dans cet exemple, l’appareil est appelé temperature-controller-01, le composant thermostat2 et la télémétrie temperature :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/telemetry/temperature?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "timestamp": "2021-03-24T12:43:44.968Z",
  "value": 70.29168040339141
}

Si l’appareil est un appareil IoT Edge, utilisez la requête suivante pour récupérer la dernière valeur connue de télémétrie d’un module. Cet exemple utilise un appareil appelé environmental-sensor-01 avec un module SimulatedTemperatureSensor et une télémétrie ambient. Le type de télémétrie ambient a des valeurs de température et d’humidité :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/telemetry/ambient?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "timestamp": "2021-03-25T15:44:34.955Z",
  "value": {
    "temperature": 21.18032378129676,
    "humidity": 25
  }
}

Conseil

Pour accéder aux données de télémétrie à partir d’un composant dans un module, utilisez /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Lire les propriétés

Utilisez la requête suivante pour récupérer les valeurs de propriété à partir d’un appareil qui n’utilise pas de composants. Dans cet exemple, l’appareil est appelé thermostat-01 :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31

La réponse à cette demande se présente comme dans l’exemple suivant. Elle indique que l’appareil signale une seule valeur de propriété :

{
  "maxTempSinceLastReboot": 93.95907131817654,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T12:47:46.7571438Z"
    }
  }
}

Utilisez la requête suivante pour récupérer des valeurs de propriété à partir de tous les composants. Dans cet exemple, l’appareil est appelé temperature-controller-01 :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/properties?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "serialNumber": "Explicabo animi nihil qui facere sit explicabo nisi.",
  "$metadata": {
    "serialNumber": {
      "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
    }
  },
  "thermostat1": {
    "maxTempSinceLastReboot": 79.7290121339184,
    "$metadata": {
      "maxTempSinceLastReboot": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    }
  },
  "thermostat2": {
    "maxTempSinceLastReboot": 54.214860556320424,
    "$metadata": {
      "maxTempSinceLastReboot": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    }
  },
  "deviceInformation": {
    "manufacturer": "Eveniet culpa sed sit omnis.",
    "$metadata": {
      "manufacturer": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "model": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "swVersion": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "osName": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "processorArchitecture": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "processorManufacturer": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "totalStorage": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "totalMemory": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    },
    "model": "Necessitatibus id ab dolores vel eligendi fuga.",
    "swVersion": "Ut minus ipsum ut omnis est asperiores harum.",
    "osName": "Atque sit omnis eum sapiente eum tenetur est dolor.",
    "processorArchitecture": "Ratione enim dolor iste iure.",
    "processorManufacturer": "Aliquam eligendi sit ipsa.",
    "totalStorage": 36.02825898541592,
    "totalMemory": 55.442695395750505
  }
}

Utilisez la requête suivante pour récupérer une valeur de propriété à partir d’un composant individuel. Dans cet exemple, l’appareil est appelé temperature-controller-01 et le composant est appelé thermostat2 :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "maxTempSinceLastReboot": 24.445128131004935,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T14:03:53.787491Z"
    }
  }
}

Si l’appareil est un appareil IoT Edge, utilisez la requête suivante pour récupérer les valeurs de propriété à partir d’un module. Cet exemple utilise un appareil appelé environmental-sensor-01 avec un module SimulatedTemperatureSensor :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "$metadata": {
    "SendData": {
      "desiredValue": true,
      "desiredVersion": 1
    },
    "SendInterval": {
      "desiredValue": 10,
      "desiredVersion": 1
    }
  }
}

Conseil

Pour accéder aux propriétés à partir d’un composant dans un module, utilisez /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Propriétés d’écriture

Certaines propriétés sont accessibles en écriture. Dans l’exemple de modèle thermostat, la targetTemperature propriété est une propriété accessible en écriture.

Utilisez la requête suivante pour écrire une valeur de propriété individuelle sur un appareil qui n’utilise pas de composants. Dans cet exemple, l’appareil est appelé thermostat-01 :

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31

Le corps de votre requête ressemble à l’exemple suivant :

{
  "targetTemperature": 65.5
}

La réponse à cette demande ressemble à l’exemple suivant :

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Conseil

Pour mettre à jour toutes les propriétés sur un appareil, utilisez PUT à la place de PATCH.

Utilisez la requête suivante pour écrire une valeur de propriété individuelle sur un appareil qui utilise des composants. Dans cet exemple, l’appareil est appelé temperature-controller-01 et le composant est appelé thermostat2 :

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

Le corps de votre requête ressemble à l’exemple suivant :

{
  "targetTemperature": 65.5
}

La réponse à cette demande ressemble à l’exemple suivant :

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Conseil

Pour mettre à jour toutes les propriétés sur un composant, utilisez PUT à la place de PATCH.

Si l’appareil est un appareil IoT Edge, utilisez la requête suivante pour écrire une valeur de propriété individuelle dans un module. Cet exemple utilise un appareil appelé environmental-sensor-01, un module SimulatedTemperatureSensor et une propriété SendInterval :

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

Le corps de votre requête ressemble à l’exemple suivant :

{
  "SendInterval": 20
}

La réponse à cette demande ressemble à l’exemple suivant :

{
  "$metadata": {
    "SendInterval": {
      "desiredValue": 20
    }
  }
}

Conseil

Pour mettre à jour toutes les propriétés d’un module, utilisez PUT au lieu de PATCH.

Mettre à jour les propriétés de module

Si vous utilisez un appareil IoT Edge, utilisez la requête suivante pour récupérer les valeurs de propriété à partir d’un module :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/properties?api-version=2022-07-31

Si vous utilisez un appareil IoT Edge, utilisez la requête suivante pour récupérer les valeurs de propriété à partir d’un composant dans un module :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties?api-version=2022-07-31

Appeler des commandes

Vous pouvez utiliser l’API REST pour appeler des commandes d’appareil et récupérer l’historique des commandes.

Utilisez la requête suivante pour appeler une commande sur un appareil qui n’utilise pas de composants. Dans cet exemple, l’appareil est appelé thermostat-01 et la commande getMaxMinReport :

POST https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

Le corps de votre requête ressemble à l’exemple suivant :

{
  "request": "2021-03-24T12:55:20.789Z"
}

La réponse à cette demande ressemble à l’exemple suivant :

{
  "response": {
    "maxTemp": 21.002000799562367,
    "minTemp": 73.09674605264892,
    "avgTemp": 59.54553991653756,
    "startTime": "2022-02-28T15:02:56.789Z",
    "endTime": "2021-05-05T03:50:56.412Z"
  },
  "responseCode": 200
}

Pour afficher l’historique de cette commande, utilisez la requête suivante :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "value": [
    {
      "response": {
        "maxTemp": 71.43744908819954,
        "minTemp": 51.29986610160005,
        "avgTemp": 39.577384387771744,
        "startTime": "2021-06-20T00:38:17.620Z",
        "endTime": "2022-01-07T22:30:41.104Z"
      },
      "responseCode": 200
    }
  ]
}

Utilisez la requête suivante pour appeler une commande sur un appareil qui utilise des composants. Dans cet exemple, l’appareil est appelé temperature-controller-01, le composant thermostat2 et la commande getMaxMinReport :

POST https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

Les formats de charge utile de la demande et de réponse sont les mêmes que pour un appareil qui n’utilise pas de composants.

Pour afficher l’historique de cette commande, utilisez la requête suivante :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

Conseil

Pour appeler des commandes dans un composant de module, utilisez /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Étapes suivantes

Maintenant que vous savez comment contrôler les appareils dans l’API REST, nous vous suggérons d’apprendre à utiliser l’API REST IoT Central pour créer et gérer des tâches.