Compartilhar via

Como usar a API REST do IoT Central para controlar dispositivos

  • Artigo

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

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

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

Um dispositivo pode agrupar as propriedades, a telemetria e os comandos aos quais ele dá suporte em componentes e módulos.

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

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

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 funcionalidades do dispositivo. Para saber mais sobre os componentes e os modelos de dispositivos, confira o guia de modelagem do IoT Plug and Play.

Nem todos os modelos de dispositivos usam componentes. A captura de tela a seguir mostra o modelo de dispositivo de um termostato simples em que todas as funcionalidades são definidas em uma só interface chamada Componente raiz:

Captura de tela que mostra um dispositivo simples de termostato sem componentes.

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

Captura de tela que mostra um dispositivo de controlador de temperatura com dois componentes de termostato e um componente de informações do dispositivo.

No IoT Central, um módulo refere-se a um módulo do 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 funcionalidades. A captura de tela a seguir mostra um exemplo de modelo de dispositivo que usa módulos. O dispositivo de sensor ambiental tem um módulo chamado SimulatedTemperatureSensor e uma interface herdada chamada management:

Captura de tela que mostra um dispositivo de sensor ambiental com um módulo.

Obter um componente do 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 é parecida com o exemplo a seguir. A matriz value contém os 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 do dispositivo

Use a seguinte solicitação para recuperar uma lista dos 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 é parecida com o exemplo a seguir. A matriz de módulos inclui apenas os módulos personalizados em execução no dispositivo IoT Edge, não os módulos $edgeAgent e $edgeHub integrados:

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

Ler a telemetria

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 é parecida com o seguinte exemplo:

{
  "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 temperature-controller-01, o componente é chamado thermostat2, 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 é parecida com o seguinte exemplo:

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

Se o dispositivo for um 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 environmental-sensor-01 com um módulo chamado SimulatedTemperatureSensor e uma telemetria chamada ambient. O tipo de telemetria ambient tem valores de temperatura e umidade:

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 é parecida com o seguinte exemplo:

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

Dica

Para acessar a telemetria por meio 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 da propriedade de um dispositivo que não usa componentes. Neste exemplo, o dispositivo é chamado 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 é parecida com o exemplo a seguir. Ela mostra que o dispositivo está relatando um só valor de propriedade:

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

Use a solicitação a seguir para recuperar os valores da propriedade de todos os componentes. Neste exemplo, o dispositivo é chamado 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 é parecida com o seguinte exemplo:

{
  "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 da propriedade de um componente individual. Neste exemplo, o dispositivo é chamado temperature-controller-01, e o componente é chamado thermostat2:

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 é parecida com o seguinte exemplo:

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

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

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 é parecida com o seguinte exemplo:

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

Dica

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 propriedade targetTemperature é 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 thermostat-01:

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

O corpo da solicitação é parecido com o seguinte exemplo:

{
  "targetTemperature": 65.5
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Dica

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 temperature-controller-01, e o componente é chamado thermostat2:

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 é parecido com o seguinte exemplo:

{
  "targetTemperature": 65.5
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Dica

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

Se o dispositivo for um 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 environmental-sensor-01, um módulo chamado SimulatedTemperatureSensor 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 é parecido com o seguinte exemplo:

{
  "SendInterval": 20
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

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

Dica

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

Atualizar as propriedades do módulo

Se você estiver usando um dispositivo IoT Edge, use a seguinte solicitação para recuperar os valores da 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 os valores da 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

Chamar comandos

Você pode usar a API REST para chamar comandos do 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 thermostat-01, e o comando é chamado getMaxMinReport:

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

O corpo da solicitação é parecido com o seguinte exemplo:

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

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "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 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 é parecida com o seguinte exemplo:

{
  "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 temperature-controller-01, o componente é chamado thermostat2, e o comando é chamado getMaxMinReport:

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

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

Para ver 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

Dica

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

Próximas etapas

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