Uso de la API REST de IoT Central para administrar dispositivos

Artículo
03/11/2024

La API de REST de IoT Central permite desarrollar aplicaciones cliente que se integran con aplicaciones de IoT Central. Puede usar la API REST para administrar dispositivos en la aplicación de IoT Central.

Cada llamada a la API REST de IoT Central requiere un encabezado de autorización. Para obtener más información, vea los procedimientos de autenticación y autorización de llamadas a la API REST de IoT Central.

Para ver la documentación de referencia sobre la API REST de IoT Central, consulte Referencia de la API REST de Azure IoT Central.

Sugerencia

Puede usar Postman para probar las llamadas API REST que se describen en este artículo. Descargue la colección de Postman de IoT Central e impórtela en Postman. En la colección, deberá establecer variables como el subdominio de la aplicación y el token de administrador.

Para obtener información sobre cómo administrar dispositivos mediante la interfaz de usuario de IoT Central, consulte Administración de dispositivos individuales en la aplicación de Azure IoT Central.

API REST de dispositivos

La API de REST de IoT Central le permite:

Agregar un dispositivo a la aplicación
Actualizar un dispositivo en la aplicación
Obtener una lista de los dispositivos en la aplicación
Obtener un dispositivo por identificador
Obtener una credencial de dispositivo
Eliminar dispositivo en la aplicación
Filtrar la lista de dispositivos en la aplicación

Agregar un dispositivo

Use la siguiente solicitud para crear un nuevo dispositivo.

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

En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega un dispositivo para una plantilla de dispositivo. Puede obtener los detalles de template en la página de plantillas de dispositivo de la interfaz de usuario de la aplicación de IoT Central.

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

El cuerpo de la solicitud tiene algunos campos obligatorios:

@displayName: nombre para mostrar del dispositivo.
@enabled: declara que este objeto es una interfaz.
@etag: ETag se usa para evitar conflictos en las actualizaciones del dispositivo.
simulated: ¿el dispositivo está simulado?
template: la definición de plantilla de dispositivo para el dispositivo.

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Obtención de un dispositivo

Use la siguiente solicitud para recuperar detalles de un dispositivo desde la aplicación:

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

Nota:

Puede obtener deviceId desde la interfaz de usuario de la aplicación de IoT Central si mantiene el mouse sobre un dispositivo.

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

La siguiente tabla muestra cómo el valor de estado de un dispositivo en la interfaz de usuario se corresponde con los valores utilizados por la API de REST para interactuar con los dispositivos:

Estado de la Interfaz de usuario del dispositivo	Notas	Obtener API REST
A la espera de aprobación	La opción de aprobación automática está deshabilitada en el grupo de conexión de dispositivos y el dispositivo no se ha agregado a través de la interfaz de usuario. Un usuario debe aprobar manualmente el dispositivo a través de la interfaz de usuario antes de poder utilizarlo.	`Provisioned: false` `Enabled: false`
Registered	Se ha aprobado un dispositivo de forma automática o manual.	`Provisioned: false` `Enabled: true`
aprovisionado	El dispositivo se ha aprovisionado y puede conectarse a su aplicación IoT Central.	`Provisioned: true` `Enabled: true`
Bloqueado	El dispositivo no puede conectarse a su aplicación IoT Central. Puede bloquear un dispositivo que se encuentre en cualquiera de los otros estados.	`Provisioned:` depende de `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

Obtención de las credenciales del dispositivo

Use la siguiente solicitud para recuperar las credenciales de un dispositivo desde la aplicación:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Actualizar un dispositivo

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

El cuerpo de la solicitud de ejemplo siguiente cambia el campo enabled a false:

{
  "enabled": false
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Eliminar un dispositivo

Use la siguiente solicitud para eliminar un dispositivo:

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

Enumerar los dispositivos.

Use la siguiente solicitud para recuperar una lista de dispositivos de la aplicación:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "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
        }
    ]
}

Asignación de un manifiesto de implementación

Si agrega un dispositivo IoT Edge, puede usar la API para asignar un manifiesto de implementación de IoT Edge al dispositivo. Para obtener más información, consulte Asignación de un manifiesto de implementación a un dispositivo.

Uso de filtros ODATA

En la versión preliminar de la API (api-version=2022-10-31-preview), puede usar filtros ODATA para filtrar y ordenar los resultados devueltos por la API Enumerar dispositivos.

maxpagesize

Use maxpagesize para establecer el tamaño del resultado. El tamaño de resultado máximo devuelto es 100, y el predeterminado, 25.

Use la siguiente solicitud para recuperar un dispositivo de los 10 principales de la aplicación:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "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 respuesta incluye un valor nextLink, que puede usar para recuperar la siguiente página de resultados.

filter

Use filter para crear expresiones que filtren la lista de dispositivos. En la siguiente tabla se muestran los operadores de comparación que puede usar:

Operadores de comparación	Símbolo	Ejemplo
Igual a	eq	`id eq 'device1' and scopes eq 'redmond'`
No es igual	ne	`Enabled ne true`
Menor o igual que	le	`id le '26whl7mure6'`
Menor que	lt	`id lt '26whl7mure6'`
Mayor o igual que	ge	`id ge '26whl7mure6'`
Mayor que	gt	`id gt '26whl7mure6'`

En la siguiente tabla se muestran los operadores que puede usar en expresiones filter:

Operador lógico	Símbolo	Ejemplo
AND	y	`id eq 'device1' and enabled eq true`
O BIEN	o	`id eq 'device1' or simulated eq false`

Actualmente, filter funciona con los siguientes campos del dispositivo:

FieldName	Tipo	Description
`id`	string	Id. de dispositivo
`displayName`	string	Nombre para mostrar del dispositivo
`enabled`	boolean	Estado habilitado del dispositivo
`provisioned`	boolean	Estado aprovisionado del dispositivo
`simulated`	boolean	Estado simulado del dispositivo
`template`	string	Identificador de la plantilla de dispositivo
`scopes`	string	Identificador de la organización

Funciones admitidas de filter:

Actualmente, la única función de filtro admitida para las listas de dispositivos es la función contains:

filter=contains(displayName, 'device1')

En el siguiente ejemplo se muestra cómo recuperar todos los dispositivos cuyo nombre para mostrar contiene la cadena thermostat:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "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

Use orderby para ordenar los resultados. Actualmente, orderby solo permite ordenar por displayName. De forma predeterminada, orderby muestra los resultados en orden ascendente. Use desc para que se muestren en orden descendente, por ejemplo:

orderby=displayName
orderby=displayName desc

En el siguiente ejemplo se muestra cómo recuperar todas las plantillas de dispositivo en las que el resultado está ordenado por displayName:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "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
        }
    ]
}

También puede combinar dos o más filtros.

En el siguiente ejemplo se muestra cómo recuperar los tres dispositivos principales cuyo nombre para mostrar contiene la cadena Thermostat.

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "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"
}

Grupos de dispositivos

Puede crear grupos de dispositivos en una aplicación IoT Central para supervisar los datos agregados, usarlos con trabajos y administrar el acceso. Los grupos de dispositivos se definen mediante un filtro que selecciona los dispositivos que se van a agregar al grupo. Puede crear grupos de dispositivos en el portal de IoT Central o mediante la API.

Incorporación de un grupo de dispositivos

Use la siguiente solicitud para crear un nuevo grupo de dispositivos.

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

Al crear un grupo de dispositivos, se define un objeto filter que selecciona los dispositivos que se van a agregar al grupo. Un elemento filter identifica una plantilla de dispositivo y cualquier propiedad que coincida. En el ejemplo siguiente, se crea un grupo de dispositivos que contiene todos los dispositivos asociados a la plantilla "dtmi:modelDefinition:dtdlv2", donde la propiedad provisioned es true.

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

El cuerpo de la solicitud tiene algunos campos obligatorios:

@displayName: nombre para mostrar del grupo de dispositivos.
@filter: consulta que define qué dispositivos deben estar en este grupo.
@etag: ETag se usa para evitar conflictos en las actualizaciones del dispositivo.
description: breve resumen del grupo de dispositivos.

El campo organizaciones solo se usa cuando una aplicación tiene una jerarquía de organización definida. Para más información sobre las organizaciones, consulte Administración de las organizaciones de IoT Central.

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Obtención de un grupo de dispositivos

Use la siguiente solicitud para recuperar detalles de un grupo de dispositivos desde la aplicación:

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

deviceGroupId: identificador único para el grupo de dispositivos.

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "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"
  ]
}

Actualización de un grupo de dispositivos

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

El cuerpo de la solicitud de ejemplo es similar al siguiente ejemplo, que actualiza displayName en el grupo de dispositivos:

{
  "displayName": "New group name"
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Eliminación de un grupo de dispositivos

Use la siguiente solicitud para eliminar un grupo de dispositivos:

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

Enumeración de grupos de dispositivos

Use la siguiente solicitud para recuperar una lista de grupos de dispositivos de la aplicación:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "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\""
    }
  ]
}

Grupos de inscripción

Los grupos de inscripción se usan para administrar las opciones de autenticación de los dispositivos en la aplicación de IoT Central. Para más información, consulte Conceptos de autenticación de dispositivos en IoT Central.

Para información sobre la creación y la administración de grupos de inscripción en la interfaz de usuario, consulte Conexión de dispositivos con certificados X.509 a la aplicación de IoT Central.

Al crear un grupo de inscripción para dispositivos que usan certificados X.509, primero debe cargar el certificado raíz o intermedio en la aplicación de IoT Central.

Generación de certificados raíz y de dispositivo

En esta sección generará los certificados X.509 que necesita para conectar un dispositivo a IoT Central.

Advertencia

Esta forma de generar certificados X.509 es solo para pruebas. En un entorno de producción, debe usar su mecanismo oficial y seguro para la generación de certificados.

Vaya al script del generador de certificados en el SDK de Microsoft Azure IoT para Node.js que descargó. Instale los paquetes necesarios:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Cree un certificado raíz y luego derive un certificado de dispositivo mediante la ejecución del script:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Sugerencia

Un identificador de dispositivo puede contener letras, números y el carácter -.

Estos comandos producen los siguientes certificados raíz y de dispositivo:

filename	contenido
mytestrootcert_cert.pem	Parte pública del certificado X.509 raíz
mytestrootcert_key.pem	Clave privada del certificado X.509 raíz
mytestrootcert_fullchain.pem	Cadena de claves completa del certificado X.509 raíz
mytestrootcert.pfx	Archivo PFX del certificado X509 raíz
sampleDevice01_cert.pem	Parte pública del certificado X.509 de dispositivo
sampleDevice01_key.pem	Clave privada del certificado X.509 de dispositivo
sampleDevice01_fullchain.pem	Cadena de claves completa del certificado X.509 de dispositivo
sampleDevice01.pfx	Archivo PFX del certificado X509 de dispositivo

Tome nota de la ubicación de estos archivos. Lo necesitará más adelante.

Generación de la versión codificada en base 64 del certificado raíz

En la carpeta de la máquina local que contiene los certificados que generó, cree un archivo denominado convert.js y agregue el siguiente contenido de JavaScript:

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

Ejecute el siguiente comando para generar una versión de codificación en base 64 del certificado:

node convert.js mytestrootcert_cert.pem

Anote la versión codificada en base 64 del certificado. Lo necesitará más adelante.

Incorporación de un grupo de inscripción X.509

Use la siguiente solicitud para crear un grupo de inscripción con myx509eg como identificador:

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

En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega un nuevo grupo de inscripción X.509:

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

El cuerpo de la solicitud tiene algunos campos obligatorios:

@displayName: nombre para mostrar del grupo de inscripción.
@enabled: indica si los dispositivos que usan el grupo pueden conectarse a IoT Central.
@type: tipo de dispositivos que se conectan mediante el grupo, ya sea iot o iotEdge.
attestation: mecanismo de atestación para el grupo de inscripción, ya sea symmetricKey o x509.

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Incorporación de un certificado X.509 a un grupo de inscripción

Use la siguiente solicitud para establecer el certificado X.509 principal del grupo de inscripción myx509eg:

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

Use esta solicitud para agregar un certificado X.509 principal o secundario al grupo de inscripción.

En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega un certificado X.509 a un grupo de inscripción:

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

certificate: la versión en base 64 del certificado que anotó anteriormente.
verified: true si atestigua que el certificado es válido, false si necesita demostrar su validez.

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Generación de código de verificación para un certificado X.509

Use la siguiente solicitud para generar un código de verificación para el certificado X.509 principal o secundario de un grupo de inscripción.

Si se establece verified en false en la solicitud anterior, use la siguiente solicitud para generar un código de verificación para el certificado X.509 principal en el grupo de inscripción myx509eg:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Tome nota de la contraseña, ya que la necesitará en el próximo paso.

Generación del certificado de verificación

Use el siguiente comando para generar un certificado de verificación a partir del código de verificación del paso anterior:

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

Ejecute el comando siguiente para generar una versión codificada en base 64 del certificado:

node convert.js verification_cert.pem

Anote la versión codificada en base 64 del certificado. Lo necesitará más adelante.

Comprobación del certificado X.509 de un grupo de inscripción

Use la siguiente solicitud para comprobar el certificado X.509 principal del grupo de inscripción myx509eg proporcionando el certificado con el código de verificación firmado:

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

En el ejemplo siguiente se muestra un cuerpo de solicitud que comprueba un certificado X.509:

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

Obtención del certificado X.509 de un grupo de inscripción

Use la siguiente solicitud para recuperar los detalles del certificado X.509 de un grupo de inscripción de la aplicación:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Eliminación de un certificado X.509 de un grupo de inscripción

Use la siguiente solicitud para eliminar el certificado X.509 principal de un grupo de inscripción con el identificador myx509eg:

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

Incorporación de un grupo de inscripción de clave simétrica

Use la siguiente solicitud para crear un grupo de inscripción con mysymmetric como identificador:

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

En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega un nuevo grupo de inscripción:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "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 genera las claves simétricas principal y secundaria al realizar esta llamada API.

Obtención de un grupo de inscripción

Use la siguiente solicitud para recuperar los detalles de un grupo de inscripción con mysymmetric como identificador:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Actualización de un grupo de inscripción

Use la siguiente solicitud para actualizar un grupo de inscripción.

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

En el ejemplo siguiente se muestra un cuerpo de solicitud que actualiza el nombre para mostrar de un grupo de inscripciones:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "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="
}

Eliminación de un grupo de inscripción

Use la siguiente solicitud para eliminar un grupo de inscripción con el identificador myx509eg:

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

Enumeración de los grupos de inscripción

Use la siguiente solicitud para recuperar una lista de los grupos de dispositivos de la aplicación:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "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="
        }
    ]
}

Share via

Uso de la API REST de IoT Central para administrar dispositivos

API REST de dispositivos

Agregar un dispositivo

Obtención de un dispositivo

Obtención de las credenciales del dispositivo

Actualizar un dispositivo

Eliminar un dispositivo

Enumerar los dispositivos.

Asignación de un manifiesto de implementación

Uso de filtros ODATA

maxpagesize

filter

orderby

Grupos de dispositivos

Incorporación de un grupo de dispositivos

Obtención de un grupo de dispositivos

Actualización de un grupo de dispositivos

Eliminación de un grupo de dispositivos

Enumeración de grupos de dispositivos

Grupos de inscripción

Creación de un grupo de inscripción

Generación de certificados raíz y de dispositivo

Generación de la versión codificada en base 64 del certificado raíz

Incorporación de un grupo de inscripción X.509

Incorporación de un certificado X.509 a un grupo de inscripción

Generación de código de verificación para un certificado X.509

Generación del certificado de verificación

Comprobación del certificado X.509 de un grupo de inscripción

Obtención del certificado X.509 de un grupo de inscripción

Eliminación de un certificado X.509 de un grupo de inscripción

Incorporación de un grupo de inscripción de clave simétrica

Obtención de un grupo de inscripción

Actualización de un grupo de inscripción

Eliminación de un grupo de inscripción

Enumeración de los grupos de inscripción

Recursos adicionales