Como utilizar a API REST do IoT Central para controlar dispositivos

  • Artigo

A API REST do IoT Central permite desenvolver aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para controlar dispositivos em seu aplicativo IoT Central. A API REST permite:

  • Leia o último valor de telemetria conhecido de um dispositivo.
  • Leia valores de propriedade de um dispositivo.
  • Defina propriedades graváveis em um dispositivo.
  • Chamar comandos em um dispositivo.

Este artigo descreve como usar a /devices/{device_id} API para controlar dispositivos individuais. Você também pode usar trabalhos para controlar dispositivos em massa.

Um dispositivo pode agrupar as propriedades, telemetria e comandos que suporta em componentes e módulos.

Cada chamada à API REST do IoT Central requer um cabeçalho de autorização. Para saber mais, consulte Como autenticar e autorizar chamadas de API REST do IoT Central.

Para obter a documentação de referência da API REST do IoT Central, consulte Referência da API REST do Azure IoT Central.

Gorjeta

Você pode usar o Postman para experimentar as chamadas de API REST descritas neste artigo. Faça o download da coleção IoT Central Postman e importe-a para o Postman. Na coleção, você precisará definir variáveis como o subdomínio do aplicativo e o token de administrador.

Para saber como controlar dispositivos usando a interface do usuário do IoT Central, consulte

Componentes e módulos

Os componentes permitem agrupar e reutilizar recursos do dispositivo. Para saber mais sobre componentes e modelos de dispositivos, consulte o guia de modelagem IoT Plug and Play.

Nem todos os modelos de dispositivo usam componentes. A captura de tela a seguir mostra o modelo de dispositivo para um termostato simples onde todos os recursos são definidos em uma única interface chamada componente raiz:

Screenshot that shows a simple no component thermostat device.

A captura de tela a seguir mostra um modelo de dispositivo controlador de temperatura que usa componentes. O controlador de temperatura tem dois componentes de termostato e um componente de informação do dispositivo:

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

No IoT Central, um módulo refere-se a um módulo IoT Edge em execução em um dispositivo IoT Edge conectado. Um módulo pode ter um modelo simples, como o termostato, que não usa componentes. Um módulo também pode usar componentes para organizar um conjunto mais complexo de recursos. A captura de tela a seguir mostra um exemplo de um modelo de dispositivo que usa módulos. O dispositivo sensor ambiental tem um módulo chamado SimulatedTemperatureSensor e uma interface herdada chamada management:

Screenshot that shows an environmental sensor device with a module.

Obter um componente de dispositivo

Use a seguinte solicitação para recuperar os componentes de um dispositivo chamado temperature-controller-01:

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

A resposta a essa solicitação se parece com o exemplo a seguir. A value matriz contém detalhes de cada componente do 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."
    }
  ]
}

Obter um módulo de dispositivo

Use a seguinte solicitação para recuperar uma lista de módulos em execução em um dispositivo IoT Edge conectado chamado environmental-sensor-01:

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

A resposta a essa solicitação se parece com o exemplo a seguir. A matriz de módulos inclui apenas módulos personalizados em execução no dispositivo IoT Edge, não os módulos e módulos internos $edgeAgent$edgeHub :

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

Use a seguinte solicitação para recuperar uma lista dos componentes em um módulo chamado SimulatedTemperatureSensor:

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

Telemetria de leitura

Use a solicitação a seguir para recuperar o último valor de telemetria conhecido de um dispositivo que não usa componentes. Neste exemplo, o dispositivo é chamado thermostat-01 e a telemetria é chamada temperature:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Use a solicitação a seguir para recuperar o último valor de telemetria conhecido de um dispositivo que usa componentes. Neste exemplo, o dispositivo é chamado , o componente é chamado temperature-controller-01thermostat2, e a telemetria é chamada temperature:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Se o dispositivo for um dispositivo IoT Edge, use a solicitação a seguir para recuperar o último valor de telemetria conhecido de um módulo. Este exemplo usa um dispositivo chamado com um módulo chamado environmental-sensor-01SimulatedTemperatureSensor e telemetria chamada ambient. O ambient tipo de telemetria tem valores de temperatura e humidade:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Gorjeta

Para acessar a telemetria de um componente em um módulo, use /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Ler propriedades

Use a solicitação a seguir para recuperar os valores de propriedade de um dispositivo que não usa componentes. Neste exemplo, o dispositivo é chamado de thermostat-01:

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

A resposta a essa solicitação se parece com o exemplo a seguir. Ele mostra que o dispositivo está relatando um único valor de propriedade:

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

Use a solicitação a seguir para recuperar valores de propriedade de todos os componentes. Neste exemplo, o dispositivo é chamado de temperature-controller-01:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "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 a solicitação a seguir para recuperar um valor de propriedade de um componente individual. Neste exemplo, o dispositivo é chamado e o componente é chamado temperature-controller-01thermostat2:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Se o dispositivo for um dispositivo IoT Edge, use a seguinte solicitação para recuperar valores de propriedade de um módulo. Este exemplo usa um dispositivo chamado com um módulo chamado environmental-sensor-01SimulatedTemperatureSensor:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Gorjeta

Para acessar as propriedades de um componente em um módulo, use /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Propriedades de gravação

Algumas propriedades são graváveis. No modelo de termostato de exemplo, a targetTemperature propriedade é uma propriedade gravável.

Use a solicitação a seguir para gravar um valor de propriedade individual em um dispositivo que não usa componentes. Neste exemplo, o dispositivo é chamado de thermostat-01:

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

O corpo da solicitação se parece com o exemplo a seguir:

{
  "targetTemperature": 65.5
}

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Gorjeta

Para atualizar todas as propriedades em um dispositivo, use PUT em vez de PATCH.

Use a solicitação a seguir para gravar um valor de propriedade individual em um dispositivo que usa componentes. Neste exemplo, o dispositivo é chamado e o componente é chamado temperature-controller-01thermostat2:

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

O corpo da solicitação se parece com o exemplo a seguir:

{
  "targetTemperature": 65.5
}

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Gorjeta

Para atualizar todas as propriedades em um componente, use PUT em vez de PATCH.

Se o dispositivo for um dispositivo IoT Edge, use a solicitação a seguir para gravar um valor de propriedade individual em um módulo. Este exemplo usa um dispositivo chamado , um módulo chamado environmental-sensor-01SimulatedTemperatureSensor, e uma propriedade chamada SendInterval:

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

O corpo da solicitação se parece com o exemplo a seguir:

{
  "SendInterval": 20
}

A resposta a essa solicitação se parece com o exemplo a seguir:

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

Gorjeta

Para atualizar todas as propriedades em um módulo, use PUT em vez de PATCH.

Atualizar propriedades do módulo

Se você estiver usando um dispositivo IoT Edge, use a seguinte solicitação para recuperar valores de propriedade de um módulo:

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

Se você estiver usando um dispositivo IoT Edge, use a seguinte solicitação para recuperar valores de propriedade de um componente em um módulo:

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

Comandos de chamada

Você pode usar a API REST para chamar comandos de dispositivo e recuperar o histórico de comandos.

Use a solicitação a seguir para chamar um comando no dispositivo que não usa componentes. Neste exemplo, o dispositivo é chamado e o comando é chamado thermostat-01getMaxMinReport:

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

O corpo da solicitação se parece com o exemplo a seguir:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "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 exibir o histórico desse comando, use a seguinte solicitação:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "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 a solicitação a seguir para chamar um comando no dispositivo que usa componentes. Neste exemplo, o dispositivo é chamado , o componente é chamado , e o comando é chamado temperature-controller-01thermostat2getMaxMinReport:

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

Os formatos da carga útil e da resposta da solicitação são os mesmos de um dispositivo que não usa componentes.

Para exibir o histórico desse comando, use a seguinte solicitação:

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

Gorjeta

Para chamar comandos em um componente em um módulo, use /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Próximos passos

Agora que você aprendeu como controlar dispositivos com a API REST, uma próxima etapa sugerida é aprender Como usar a API REST do IoT Central para criar e gerenciar trabalhos.