Empleo de la API de REST de IoT Central para controlar dispositivos

  • Artículo

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

  • Leer el último valor de telemetría conocido de un dispositivo.
  • Leer los valores de propiedad de un dispositivo.
  • Establecer propiedades editables en un dispositivo.
  • Llamar a comandos en un dispositivo.

En este artículo se explica cómo usar la API /devices/{device_id} para controlar dispositivos individuales. También se pueden usar trabajos para controlar dispositivos en bloque.

Un dispositivo puede agrupar las propiedades, la telemetría y los comandos que admite en componentes y módulos.

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 controlar los dispositivos mediante la interfaz de usuario de IoT Central, consulte

Componentes y módulos

Los componentes permiten agrupar y reutilizar capacidades de un dispositivo. Para obtener más información sobre los componentes y los modelos de dispositivo, vea Guía de modelado de IoT Plug and Play.

No todas las plantillas de dispositivo usan componentes. En la captura de pantalla siguiente se muestra la plantilla de dispositivo de un termostato simple donde todas las capacidades se definen en una sola interfaz denominada Componente raíz:

Screenshot that shows a simple no component thermostat device.

En la captura de pantalla siguiente se muestra una plantilla de dispositivo de controlador de temperatura que usa componentes. El controlador de temperatura tiene dos componentes de termostato y un componente de información del dispositivo:

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

En IoT Central, módulo se refiere a un módulo IoT Edge que se ejecuta en un dispositivo IoT Edge conectado. Un módulo puede tener un modelo simple, como el termostato que no usa componentes. Un módulo también puede usar componentes para organizar un conjunto más complejo de capacidades. En la captura de pantalla siguiente se muestra un ejemplo de una plantilla de dispositivo que usa módulos. El dispositivo de sensor ambiental tiene un módulo de nombre SimulatedTemperatureSensor y una interfaz heredada de nombre management:

Screenshot that shows an environmental sensor device with a module.

Obtención de un componente de dispositivo

Use la siguiente solicitud para recuperar los componentes de un dispositivo de nombre temperature-controller-01:

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

La respuesta a esta solicitud es similar al ejemplo siguiente. La matriz value contiene detalles de cada componente del dispositivo:

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

Obtención de un módulo de dispositivo

Use la siguiente solicitud para recuperar una lista de módulos que se ejecutan en un dispositivo IoT Edge conectado de nombre environmental-sensor-01:

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

La respuesta a esta solicitud es similar al ejemplo siguiente. La matriz de módulos solo incluye los módulos personalizados que se ejecutan en el dispositivo IoT Edge, no los módulos $edgeAgent y $edgeHub integrados:

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

Use la siguiente solicitud para recuperar una lista de los componentes de un módulo de nombre SimulatedTemperatureSensor:

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

Lectura de telemetría

Use la siguiente solicitud para recuperar el último valor de telemetría conocido de un dispositivo que no usa componentes. En este ejemplo, el nombre del dispositivo es thermostat-01 y el de la telemetría temperature:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Use la siguiente solicitud para recuperar el último valor de telemetría conocido de un dispositivo que sí usa componentes. En este ejemplo, el nombre del dispositivo es temperature-controller-01, el del componente es thermostat2 y el de la telemetría temperature:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Si el dispositivo es un dispositivo IoT Edge, use la siguiente solicitud para recuperar el último valor de telemetría conocido de un módulo. En este ejemplo se usa un dispositivo de nombre environmental-sensor-01 con un módulo de nombre SimulatedTemperatureSensor y una telemetría de nombre ambient. El tipo de telemetría ambient tiene valores de temperatura y humedad:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Sugerencia

Para acceder a la telemetría desde un componente de un módulo, use /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Lectura de las propiedades

Use la siguiente solicitud para recuperar los valores de propiedad de un dispositivo que no usa componentes. En este ejemplo, el nombre del dispositivo es thermostat-01:

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

La respuesta a esta solicitud es similar al ejemplo siguiente. Muestra que el dispositivo comunica un solo valor de propiedad:

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

Use la siguiente solicitud para recuperar los valores de propiedad de todos los componentes. En este ejemplo, el nombre del dispositivo es temperature-controller-01:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Use la siguiente solicitud para recuperar un valor de propiedad de un componente individual. En este ejemplo, el nombre del dispositivo es temperature-controller-01 y el del componente thermostat2:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Si se trata de un dispositivo IoT Edge, use la siguiente solicitud para recuperar los valores de propiedad de un módulo. En este ejemplo se usa un dispositivo de nombre environmental-sensor-01 con un módulo de nombre SimulatedTemperatureSensor:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Sugerencia

Para acceder a las propiedades de un componente de un módulo, use /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Escritura de propiedades

Algunas propiedades son editables. En el modelo de termostato de ejemplo, la targetTemperature propiedad es una propiedad grabable.

Use la siguiente solicitud para escribir un valor de propiedad individual en un dispositivo que no usa componentes. En este ejemplo, el nombre del dispositivo es thermostat-01:

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

El cuerpo de la solicitud se parece al siguiente ejemplo:

{
  "targetTemperature": 65.5
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Sugerencia

Para actualizar todas las propiedades de un dispositivo, use PUT en lugar de PATCH.

Use la siguiente solicitud para escribir un valor de propiedad individual en un dispositivo que sí usa componentes. En este ejemplo, el nombre del dispositivo es temperature-controller-01 y el del componente thermostat2:

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

El cuerpo de la solicitud se parece al siguiente ejemplo:

{
  "targetTemperature": 65.5
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Sugerencia

Para actualizar todas las propiedades de un componente, use PUT en lugar de PATCH.

Si el dispositivo es un dispositivo IoT Edge, use la siguiente solicitud para escribir un valor de propiedad individual en un módulo. En este ejemplo se usan un dispositivo de nombre environmental-sensor-01, un módulo de nombre SimulatedTemperatureSensor y una propiedad de nombre SendInterval:

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

El cuerpo de la solicitud se parece al siguiente ejemplo:

{
  "SendInterval": 20
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Sugerencia

Para actualizar todas las propiedades de un módulo, use PUT en lugar de PATCH.

Actualización de las propiedades del módulo

Si está utilizando un dispositivo IoT Edge, utilice la siguiente solicitud para recuperar los valores de propiedad de un módulo:

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

Si está utilizando un dispositivo IoT Edge, use la siguiente solicitud para recuperar los valores de propiedad de un componente en un módulo:

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

Comandos de llamada

Puede usar la API REST para llamar a comandos de dispositivo y recuperar el historial de comandos.

Use la siguiente solicitud para llamar a un comando de un dispositivo que no usa componentes. En este ejemplo, el nombre del dispositivo es thermostat-01 y el del comando getMaxMinReport:

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

El cuerpo de la solicitud se parece al siguiente ejemplo:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Para ver el historial de este comando, use la siguiente solicitud:

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

La respuesta a esta solicitud es similar al ejemplo siguiente:

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

Use la siguiente solicitud para llamar a un comando de un dispositivo que sí usa componentes. En este ejemplo, el nombre del dispositivo es temperature-controller-01, el del componente es thermostat2 y el del comando getMaxMinReport:

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

Los formatos de la carga de la solicitud y la respuesta son iguales que para un dispositivo que no usa componentes.

Para ver el historial de este comando, use la siguiente solicitud:

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

Sugerencia

Para llamar a comandos de un componente de un módulo, use /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Pasos siguientes

Ahora que ha aprendido a controlar los dispositivos con la API REST, el siguiente paso que se sugiere es Uso de la API REST de IoT Central para crear y administrar trabajos.