Использование REST API IoT Central для управления устройствами

Статья
06/14/2023

REST API IoT Central позволяет разрабатывать клиентские приложения, которые интегрируются с приложениями IoT Central. Вы можете использовать REST API для управления устройствами в приложении IoT Central. REST API предоставляет следующие возможности.

Чтение последнего известного значения телеметрии с устройства.
Считывание значений свойств с устройства.
Настройка записываемых свойств на устройстве.
Вызов команд на устройстве.

В этой статье описывается, как использовать API /devices/{device_id} для управления отдельными устройствами. Вы также можете использовать задания, чтобы управлять группой устройств.

Устройство может объединять поддерживаемые свойства, данные телеметрии и команды в компоненты и модули.

Каждому вызову REST API IoT Central требуется заголовок авторизации. Дополнительные сведения см. в разделе Аутентификация и авторизация вызовов REST API IoT Central.

Справочную документацию по REST API IoT Central см. в справочнике по REST API Azure IoT Central.

Сведения об управлении устройствами с помощью пользовательского интерфейса IoT Central см. в статье

Компоненты и модули

Компоненты позволяют группировать и повторно использовать возможности устройств. Дополнительные сведения о компонентах и моделях устройств см. в статье Руководство по моделированию IoT Plug and Play.

Не все шаблоны устройств используют компоненты. На следующем снимке экрана показан шаблон устройства для простого термостата, где все возможности определяются в одном интерфейсе, который называется корневым компонентом.

На следующем снимке экрана показан шаблон устройства регулятора температуры, использующий компоненты. Регулятор температуры имеет два компонента термостата и компонент сведений об устройстве.

В IoT Central модуль ссылается на модуль IoT Edge, выполняющийся на подключенном устройстве IoT Edge. Модуль может иметь простую модель, например термостат, которая не использует компоненты. Модуль также может использовать компоненты для упорядочивания более сложного набора возможностей. На следующем снимке экрана показан пример шаблона устройства, использующего модули. Устройство датчика окружающей среды имеет модуль с именем SimulatedTemperatureSensor и унаследованный интерфейс management.

Получение компонента устройства

Используйте следующий запрос для получения компонентов с устройства с именем temperature-controller-01.

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

Ответ на этот запрос выглядит, как показано в примере ниже. Массив value содержит сведения о каждом компоненте устройства.

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

Получение модуля устройства

Используйте следующий запрос для получения списка модулей, выполняющихся на подключенном устройстве IoT Edge с именем environmental-sensor-01.

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

Ответ на этот запрос выглядит, как показано в примере ниже. Массив модулей включает в себя только пользовательские модули, работающие на устройстве IoT Edge, а не встроенные модули $edgeAgent и $edgeHub.

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

Используйте следующий запрос для получения списка компонентов в модуле с именем SimulatedTemperatureSensor.

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

Чтение телеметрии

Используйте следующий запрос для получения последнего известного значения телеметрии с устройства, которое не использует компоненты. В этом примере устройство называется thermostat-01, а телеметрия — temperature.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Используйте следующий запрос для получения последнего известного значения телеметрии с устройства, которое использует компоненты. В этом примере устройство называется temperature-controller-01, компонент — thermostat2, а телеметрия — temperature.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Если это устройство IoT Edge, используйте следующий запрос для получения последнего известного значения телеметрии из модуля. В этом примере используется устройство environmental-sensor-01 с модулем SimulatedTemperatureSensor и телеметрией ambient. Тип телеметрии ambient содержит значения температуры и влажности.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Совет

Чтобы получить доступ к данным телеметрии из компонента в модуле, используйте /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Читать свойства

Используйте следующий запрос для получения значений свойств с устройства, которое не использует компоненты. В этом примере устройство называется thermostat-01.

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

Ответ на этот запрос выглядит, как показано в примере ниже. Он показывает, что устройство сообщает об одном значении свойства.

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

Используйте следующий запрос для получения значений свойств из всех компонентов. В этом примере устройство называется temperature-controller-01.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Используйте следующий запрос для получения значений свойств из отдельного компонента. В этом примере устройство называется temperature-controller-01, а компонент — thermostat2.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Если устройство является устройством IoT Edge, используйте следующий запрос для получения значений свойств из модуля. В этом примере используется устройство environmental-sensor-01 с модулем SimulatedTemperatureSensor.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Совет

Чтобы получить доступ к свойствам из компонента в модуле, используйте /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Запись свойств

Некоторые свойства доступны для записи. В примере модели targetTemperature термостата свойство является свойством, допускаемым для записи.

Используйте следующий запрос для записи значения отдельного свойства на устройство, которое не использует компоненты. В этом примере устройство называется thermostat-01.

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

Текст запроса будет выглядеть как в следующем примере.

{
  "targetTemperature": 65.5
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Совет

Чтобы обновить все свойства на устройстве, используйте PUT вместо PATCH.

Используйте следующий запрос для записи значения отдельного свойства на устройство, которое использует компоненты. В этом примере устройство называется temperature-controller-01, а компонент — thermostat2.

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

Текст запроса будет выглядеть как в следующем примере.

{
  "targetTemperature": 65.5
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Совет

Чтобы обновить все свойства компонента, используйте PUT вместо PATCH.

Если это устройство IoT Edge, используйте следующий запрос для записи значения отдельного свойства в модуль. В этом примере используется устройство environmental-sensor-01, модуль SimulatedTemperatureSensor и свойство SendInterval.

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

Текст запроса будет выглядеть как в следующем примере.

{
  "SendInterval": 20
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Совет

Чтобы обновить все свойства в модуле, используйте PUT вместо PATCH.

Обновление свойств модуля.

Если вы используете устройство IoT Edge, используйте следующий запрос для получения значений свойств из модуля.

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

Если вы используете устройство IoT Edge, используйте следующий запрос для получения значений свойств из компонентов модуля.

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

Вызов команд

Rest API можно использовать для вызова команд устройства и получения журнала команд.

Используйте следующий запрос для вызова команды на устройстве, которое не использует компоненты. В этом примере устройство называется thermostat-01, а команда — getMaxMinReport.

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

Текст запроса будет выглядеть как в следующем примере.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Чтобы просмотреть журнал этой команды, используйте следующий запрос.

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

Ответ на этот запрос выглядит так, как показано в следующем примере.

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

Используйте следующий запрос для вызова команды на устройстве, которое использует компоненты. В этом примере устройство называется temperature-controller-01, компонент — thermostat2, а команда — getMaxMinReport.

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

Форматы полезных данных запроса и ответа совпадают с форматами для устройства, которое не использует компоненты.

Чтобы просмотреть журнал этой команды, используйте следующий запрос.

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

Совет

Чтобы вызвать команды в компоненте модуля, используйте /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Следующие шаги

Вы изучили информацию о том, как управлять устройствами с помощью REST API. Предлагаемый следующий шаг — ознакомиться с разделом Использование REST API IoT Central для создания и управления заданиями.

Поделиться через

Использование REST API IoT Central для управления устройствами

Компоненты и модули

Получение компонента устройства

Получение модуля устройства

Чтение телеметрии

Читать свойства

Запись свойств

Обновление свойств модуля.

Вызов команд

Следующие шаги

Обратная связь

Дополнительные ресурсы