Comment utiliser l’API REST IoT Central pour gérer les appareils

Article
03/01/2024

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 gérer des appareils dans votre application IoT Central.

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 gérer des appareils à l’aide de l’interface utilisateur IoT Central, consultez Gérer des appareils individuels dans votre application Azure IoT Central.

API REST de messagerie des appareils

L’API REST d’IoT Central vous permet de :

Ajouter un appareil à votre application
Mettre à jour un appareil dans votre application
Obtenir la liste des appareils dans l’application
Obtenir un appareil via son ID
Obtenir les informations d’identification de l’appareil
Supprimer un appareil dans votre application
Filtrer la liste des appareils dans l’application

Ajout d’un appareil

Utilisez la demande suivante pour créer un nouvel appareil.

PUT https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

L’exemple suivant montre un corps de demande qui ajoute un appareil pour un modèle d’appareil. Vous pouvez accéder aux détails template à partir de la page Modèles d’appareil dans l’interface utilisateur de l’application IoT Central.

{
  "displayName": "CheckoutThermostat",
  "template": "dtmi:contoso:Thermostat;1",
  "simulated": true,
  "enabled": true
}

Le corps de la demande contient des champs obligatoires :

@displayName : nom complet de l’appareil.
@enabled : déclare que cet objet est une interface.
@etag : ETag utilisé pour empêcher les conflits dans les mises à jour de l’appareil.
simulated: L’appareil est-il simulé ?
template : définition du modèle d’appareil pour l’appareil.

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Obtenir un appareil

Utilisez la demande suivante pour récupérer les détails d’un appareil à partir de votre application :

GET https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Remarque

Vous pouvez obtenir le deviceId à partir de l’interface utilisateur de l’application IoT Central en plaçant le curseur de la souris sur un appareil.

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

{
    "id": "5jcwskdwbm",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
    "displayName": "Thermostat - 5jcwskdwbm",
    "simulated": false,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Le tableau suivant montre comment la valeur d’état d’un appareil dans l’interface utilisateur est mappée aux valeurs utilisées par l’API REST pour interagir avec les appareils :

État de l’appareil d’interface utilisateur	Notes	Get de l’API REST
En attente d’approbation	L’option d’approbation automatique est désactivée dans le groupe de connexions de l’appareil et l’appareil n’a pas été ajouté via l’interface utilisateur. Un utilisateur doit approuver manuellement l’appareil via l’interface utilisateur pour pouvoir être utilisé.	`Provisioned: false` `Enabled: false`
Enregistré	Un appareil a été approuvé automatiquement ou manuellement.	`Provisioned: false` `Enabled: true`
approvisionné	L’appareil a été provisionné et peut se connecter à votre application IoT Central.	`Provisioned: true` `Enabled: true`
Bloqué	L’appareil n’est pas autorisé à se connecter à votre application IoT Central. Vous pouvez bloquer un appareil qui se trouve dans l’un des autres états.	`Provisioned:` dépend de `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

Obtention des informations d’identification d’un appareil

Utilisez la demande suivante pour récupérer les informations d’identification d’un appareil à partir de votre application :

GET https://{your app subdomain}/api/devices/{deviceId}/credentials?api-version=2022-07-31

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

{
    "idScope": "0ne003E64EF",
    "symmetricKey": {
        "primaryKey": "XUQvxGl6+Q1R0NKN5kOTmLOWsSKiuqs5N9unrjYCH4k=",
        "secondaryKey": "Qp/MTGHjn5MUTw4NVGhRfG+P+L1zh1gtAhO/KH8kn5c="
    }
}

Mettre à jour un appareil

PATCH https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

L’exemple de corps de requête suivant modifie le champ enabled en false :

{
  "enabled": false
}

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": false
}

Supprimer une unité

Pour supprimer un appareil, utilisez la requête suivante :

DELETE https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Faire la liste des appareils

Utilisez la requête suivante pour récupérer une liste d’appareils à partir de votre application :

GET https://{your app subdomain}/api/devices?api-version=2022-07-31

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Affecter un manifeste de déploiement

Si vous ajoutez un appareil IoT Edge, vous pouvez utiliser l’API pour affecter un manifeste de déploiement IoT Edge à l’appareil. Pour plus d’informations, consultez Affecter un manifeste de déploiement à un appareil.

Utiliser des filtres ODATA

Dans la préversion de l’API (api-version=2022-10-31-preview), vous pouvez utiliser des filtres ODATA pour filtrer et trier les résultats retournés par l’API Répertorier les appareils.

maxpagesize

Utilisez le filtre maxpagesize pour définir la taille des résultats. La taille maximale des résultats retournés est 100, et la taille par défaut est 25.

Utilisez la demande suivante pour récupérer les 10 principaux appareils à partir de votre application :

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdgdwbm",
            "etag": "eyJoZWdhhZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "RS40 Occupancy Sensor - 5jcwskdgdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "urn:modelDefinition:aqlyr1ulfku:tz5rut2pvx",
            "enabled": true
        },
        ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
}

La réponse comprend une valeur nextLink que vous pouvez utiliser pour récupérer la page de résultats suivante.

filter

Utilisez filter pour créer des expressions qui filtrent la liste des appareils. Le tableau suivant répertorie les opérateurs de comparaison que vous pouvez utiliser :

Opérateur de comparaison	Symbole	Exemple
Égal à	eq	`id eq 'device1' and scopes eq 'redmond'`
Différent de	ne	`Enabled ne true`
Inférieur ou égal à	le	`id le '26whl7mure6'`
Inférieur à	lt	`id lt '26whl7mure6'`
Supérieur ou égal à	ge	`id ge '26whl7mure6'`
Supérieur(e) à	gt	`id gt '26whl7mure6'`

Le tableau suivant montre les opérateurs logiques qu'il est possible d'utiliser dans les expressions filter :

Opérateur logique	Symbole	Exemple
AND	et	`id eq 'device1' and enabled eq true`
OR	or	`id eq 'device1' or simulated eq false`

Actuellement, filter fonctionne avec les champs d’appareil suivants :

FieldName	Type	Description
`id`	string	ID de périphérique
`displayName`	string	Nom d'affichage de l'appareil
`enabled`	booléen	État de l’appareil activé
`provisioned`	booléen	État provisionné de l’appareil
`simulated`	booléen	État simulé de l’appareil
`template`	string	ID du modèle d’appareil
`scopes`	string	ID d’organisation

Fonctions prises en charge par filter :

Actuellement, la seule fonction de filtre prise en charge pour les listes d’appareils est la fonction contains :

filter=contains(displayName, 'device1')

L’exemple suivant montre comment récupérer tous les appareils où le nom complet contient la chaîne thermostat :

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "thermostat1",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "thermostat2",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

orderby

Utilisez orderby pour trier les résultats. Actuellement, orderby vous permet de trier uniquement sur displayName. Par défaut, orderby trie dans l’ordre croissant. Utilisez desc pour effectuer un tri dans l’ordre décroissant, par exemple :

orderby=displayName
orderby=displayName desc

L’exemple suivant montre comment récupérer tous les modèles d’appareil où le résultat est trié par displayName :

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName

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

{
    "value": [
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Vous pouvez également combiner deux ou plusieurs filtres.

L’exemple suivant montre comment récupérer les trois principaux appareils où le nom d’affichage contient la chaîne Thermostat.

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3

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

{
  "value": [
    {
      "id": "1fpwlahp0zp",
      "displayName": "Thermostat - 1fpwlahp0zp",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "1yg0zvpz9un",
      "displayName": "Thermostat - 1yg0zvpz9un",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "20cp9l96znn",
      "displayName": "Thermostat - 20cp9l96znn",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    }
  ],
  "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
}

Groupes d'appareils

Vous pouvez créer des groupes d’appareils dans une application IoT Central pour surveiller les données agrégées, les utiliser avec des travaux et gérer l’accès. Les groupes d’appareils sont définis par un filtre qui sélectionne les appareils à ajouter au groupe. Vous pouvez créer des groupes d’appareils dans le portail IoT Central ou à l’aide de l’API.

Ajouter un groupe d’appareils

Utilisez la requête suivante pour créer un nouveau groupe d’appareils.

PUT https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Lorsque vous créez un groupe d’appareils, vous définissez un filter qui sélectionne les appareils à ajouter au groupe. Un filter identifie un modèle d’appareil et toutes les propriétés à mettre en correspondance. L’exemple suivant crée un groupe d’appareils contenant tous les appareils associés au modèle « dtmi:modelDefinition:dtdlv2 » où la propriété provisioned est true.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Le corps de la demande contient des champs obligatoires :

@displayName : nom d’affichage du groupe d’appareils.
@filter: requête définissant les appareils qui doivent se trouver dans ce groupe.
@etag : ETag utilisé pour empêcher les conflits dans les mises à jour de l’appareil.
description : résumé court du groupe d’appareils.

Le champ « organizations » est utilisé uniquement quand une hiérarchie d’organisation est définie pour une application. Pour en savoir plus sur les organisations, consultez Gérer les organisations IoT Central.

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

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Obtenir un groupe d’appareils

Utilisez la re suivante pour récupérer les détails d’un groupe d’appareils à partir de votre application :

GET https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

deviceGroupId : ID unique du groupe d’appareils.

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

{
  "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
  "displayName": "DeviceGroupEntry1",
  "description": "This is a default device group containing all the devices for this particular Device Template.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Mettre à jour un groupe d’appareils

PATCH https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

L’exemple de corps de requête ressemble à l’exemple suivant, qui met à jour le displayName du groupe d’appareils :

{
  "displayName": "New group name"
}

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

{
  "id": "group1",
  "displayName": "New group name",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Supprimer un groupe d’appareils

Utilisez la requête suivante pour supprimer un groupe d’appareils :

DELETE https://{your app subdomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Répertorier les groupes d’appareils

Utilisez la requête suivante pour récupérer une liste de groupes d’appareils à partir de votre application :

GET https://{your app subdomain}/api/deviceGroups?api-version=2022-07-31

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

{
  "value": [
    {
      "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
      "displayName": "DeviceGroupEntry1",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
      "organizations": [
        "seattle"
      ]
    },
    {
      "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
      "displayName": "DeviceGroupEntry2",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
      "organizations": [
        "redmond"
      ]
    },
    {
      "id": "241ad72b-32aa-4216-aabe-91b240582c8d",
      "displayName": "DeviceGroupEntry3",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
    },
    {
      "id": "group4",
      "displayName": "DeviceGroupEntry4",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
    }
  ]
}

Groupes d’inscription

Les groupes d’inscriptions permettent de gérer les options d’authentification des appareils dans votre application IoT Central. Pour en savoir plus, consultez Concepts d’authentification des appareils dans IoT Central.

Pour savoir comment créer et gérer des groupes d’inscriptions dans l’interface utilisateur, consultez le guide pratique pour connecter des appareils avec des certificats X.509 à une application IoT Central.

Quand vous créez un groupe d’inscriptions pour des appareils qui utilisent des certificats X.509, vous devez d’abord charger le certificat racine ou intermédiaire dans votre application IoT Central.

Générer des certificats racines et d’appareil

Dans cette section, vous générez les certificats X.509 dont vous avez besoin pour connecter un appareil à IoT Central.

Avertissement

Cette façon de générer des certificats X.509 est destinée aux tests uniquement. Dans le cas d’un environnement de production, vous devez utiliser votre mécanisme sécurisé officiel pour la génération de certificats.

Accédez au script du générateur de certificats dans le SDK Microsoft Azure IoT pour Node.js que vous avez téléchargé. Installez les packages nécessaires :
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Créez un certificat racine, puis dérivez un certificat d’appareil en exécutant le script :
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Conseil

Un ID d’appareil peut contenir des lettres, des chiffres et le caractère -.

Ces commandes génèrent les certificats racines et les certificats d’appareil suivants :

Nom de fichier	Contenus
mytestrootcert_cert.pem	Partie publique du certificat X.509 racine
mytestrootcert_key.pem	Clé privée du certificat X.509 racine
mytestrootcert_fullchain.pem	Trousseau complet du certificat X.509 racine
mytestrootcert.pfx	Fichier PFX du certificat X.509 racine
sampleDevice01_cert.pem	Partie publique du certificat X.509 de l’appareil
sampleDevice01_key.pem	Clé privée du certificat X.509 de l’appareil
sampleDevice01_fullchain.pem	Trousseau complet du certificat X.509 de l’appareil
sampleDevice01.pfx	Fichier PFX du certificat X.509 de l’appareil

Notez l’emplacement de ces fichiers. Vous en aurez besoin ultérieurement.

Générer la version encodée en base 64 du certificat racine

Dans le dossier de votre ordinateur local qui contient les certificats que vous avez générés, créez un fichier appelé convert.js et ajoutez le contenu JavaScript suivant :

const fs = require('fs')
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
console.log(fileContents);

Exécutez la commande suivante pour générer une version encodée en base 64 du certificat :

node convert.js mytestrootcert_cert.pem

Notez la version encodée en base 64 du certificat. Vous en aurez besoin ultérieurement.

Ajouter un groupe d’inscriptions X.509

Utilisez la demande suivante pour créer un groupe d’inscriptions avec myx509eg comme ID :

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

L’exemple suivant montre un corps de demande qui ajoute un nouveau groupe d’inscriptions X.509 :

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "x509"
  }
}

Le corps de la demande contient des champs obligatoires :

@displayName : nom d’affichage du compte d’inscriptions.
@enabled : indique si les appareils utilisant le groupe sont autorisés à se connecter à IoT Central.
@type : type des appareils se connectant par le biais le groupe (iot ou iotEdge).
attestation : mécanisme d’attestation pour le groupe d’inscriptions (symmetricKey ou x509).

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

{
    "id": "myEnrollmentGroupId",
    "displayName": "My group",
    "enabled": true,
    "type": "iot",
    "attestation": {
        "type": "x509",
        "x509": {
            "signingCertificates": {}
        }
    },
    "etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
}

Ajouter un certificat X.509 à un groupe d’inscriptions

Utilisez la demande suivante pour définir le certificat X.509 principal du groupe d’inscriptions myx509eg :

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Utilisez cette demande pour ajouter un certificat X.509 principal ou secondaire au groupe d’inscriptions.

L’exemple suivant montre un corps de demande qui ajoute un certificat X.509 à un groupe d’inscriptions :

{
  "verified": false,
  "certificate": "<base64-certificate>"
}

certificate - Version en base 64 du certificat que vous avez noté précédemment.
verified - true si vous attestez que le certificat est valide, false si vous devez prouver la validité du certificat.

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

{
  "verified": false,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Générer un code de vérification pour un certificat X.509

Utilisez la demande suivante pour générer un code de vérification pour le certificat X.509 principal ou secondaire d’un groupe d’inscriptions.

Si vous avez défini verified sur false dans la demande précédente, utilisez la demande suivante pour générer un code de vérification pour le certificat X.509 principal dans le groupe d’inscriptions myx509eg :

POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31

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

{
  "verificationCode": "<certificate-verification-code>"
}

Notez le code de vérification, car vous en aurez besoin à l’étape suivante.

Générer le certificat de vérification

Utilisez la commande suivante pour générer un certificat de vérification à partir du code de vérification de l’étape précédente :

node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

Exécutez la commande suivante pour générer une version encodée en base 64 du certificat :

node convert.js verification_cert.pem

Notez la version encodée en base 64 du certificat. Vous en aurez besoin ultérieurement.

Vérifier le certificat X.509 d’un groupe d’inscriptions

Utilisez la demande suivante pour vérifier le certificat X.509 principal du groupe d’inscriptions myx509eg en fournissant le certificat avec le code de vérification signé :

POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31

L’exemple suivant montre un corps de demande qui vérifie un certificat X.509 :

{
  "certificate": "base64-verification-certificate"
}

Obtenir le certificat X.509 d’un groupe d’inscriptions

Utilisez la demande suivante pour récupérer les détails du certificat X.509 d’un groupe d’inscriptions à partir de votre application :

GET https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

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

{
  "verified": true,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Supprimer un certificat X.509 d’un groupe d’inscriptions

Utilisez la demande suivante pour supprimer le certificat X.509 principal d’un groupe d’inscriptions avec l’ID myx509eg :

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Ajouter un groupe d’inscriptions avec clé symétrique

Utilisez la demande suivante pour créer un groupe d’inscriptions avec mysymmetric comme ID :

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/mysymmetric?api-version=2022-07-31

L’exemple suivant montre un corps de demande qui ajoute un nouveau groupe d’inscriptions :

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey"
  }
}

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

IoT Central génère les clés symétriques primaire et secondaire quand vous effectuez cet appel d’API.

Obtenir un groupe d’inscriptions

Utilisez la demande suivante pour récupérer les détails d’un groupe d’inscriptions avec mysymmetric comme ID :

GET https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/mysymmetric?api-version=2022-07-31

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Mettre à jour un groupe d’inscriptions

Utilisez la demande suivante pour mettre à jour un groupe d’inscriptions.

PATCH https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

L’exemple suivant montre un corps de requête qui met à jour le nom d’affichage d’un groupe d’inscription :

{
  "displayName": "My new group name",
}

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

{
  "id": "myEnrollmentGroupId",
  "displayName": "My new group name",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Supprimer un groupe d’inscriptions

Utilisez la demande suivante pour supprimer un groupe d’inscriptions avec l’ID myx509eg :

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Lister les groupes d’inscriptions

Utilisez la demande suivante pour récupérer une liste de groupes d’inscription à partir de votre application :

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

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

{
    "value": [
        {
            "id": "myEnrollmentGroupId",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "symmetricKey",
                "symmetricKey": {
                    "primaryKey": "primaryKey",
                    "secondaryKey": "secondarykey"
                }
            },
            "etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
        },
        {
            "id": "enrollmentGroupId2",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "x509",
                "x509": {
                    "signingCertificates": {}
                }
            },
            "etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
        }
    ]
}

Partager via

Comment utiliser l’API REST IoT Central pour gérer les appareils

API REST de messagerie des appareils

Ajout d’un appareil

Obtenir un appareil

Obtention des informations d’identification d’un appareil

Mettre à jour un appareil

Supprimer une unité

Faire la liste des appareils

Affecter un manifeste de déploiement

Utiliser des filtres ODATA

maxpagesize

filter

orderby

Groupes d'appareils

Ajouter un groupe d’appareils

Obtenir un groupe d’appareils

Mettre à jour un groupe d’appareils

Supprimer un groupe d’appareils

Répertorier les groupes d’appareils

Groupes d’inscription

Création d’un groupe d’inscription

Générer des certificats racines et d’appareil

Générer la version encodée en base 64 du certificat racine

Ajouter un groupe d’inscriptions X.509

Ajouter un certificat X.509 à un groupe d’inscriptions

Générer un code de vérification pour un certificat X.509

Générer le certificat de vérification

Vérifier le certificat X.509 d’un groupe d’inscriptions

Obtenir le certificat X.509 d’un groupe d’inscriptions

Supprimer un certificat X.509 d’un groupe d’inscriptions

Ajouter un groupe d’inscriptions avec clé symétrique

Obtenir un groupe d’inscriptions

Mettre à jour un groupe d’inscriptions

Supprimer un groupe d’inscriptions

Lister les groupes d’inscriptions

Commentaires

Ressources supplémentaires