Общие сведения о двойниках устройств и их использование в Центре Интернета вещей
Двойники устройств — это документы JSON, хранящие сведения о состоянии устройства, в том числе метаданные, конфигурации и условия. Центр Интернета вещей Azure сохраняет двойник устройства для каждого устройства, подключаемого к Центру Интернета вещей.
Примечание.
Функции, описанные в этой статье, доступны только на стандартном уровне Центра Интернета вещей. Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.
В этой статье рассматриваются следующие вопросы:
- Структура двойника устройства: теги, требуемые свойства и сообщаемые свойства.
- Операции, выполняемые приложениями устройств и внутренней частью решения, могут выполняться на двойниках устройств.
Двойники устройства используются для выполнения следующих действий:
Хранение метаданных для конкретного устройства в облаке. Например, расположение виртуального компьютера.
Сообщение сведений о текущем состоянии приложения устройства, таких как доступные возможности и условия. Например, подключение устройства к центру Интернета вещей по сети мобильной связи или Wi-Fi.
Синхронизируйте состояние длительных рабочих процессов между приложением устройства и внутренними приложениями. Например, если серверное приложение указывает новую версию встроенного ПО для установки, а приложение устройства сообщает о различных этапах процесса обновления.
выполнение запроса метаданных, конфигурации или состояния устройства.
Дополнительные сведения об использовании сообщаемых свойств, сообщений устройства в облако или отправки файлов см . в руководстве по обмену данными между устройствами и облаком.
Дополнительные сведения об использовании нужных свойств, прямых методов или сообщений об использовании сообщений между облаком и устройствами см . в руководстве по обмену данными между устройствами.
Сведения о том, как двойники устройства связаны с моделью, используемой устройством Azure IoT Plug and Play, см. в статье Общие сведения о цифровых двойниках устройств IoT Plug and Play.
Двойники устройств
Двойники устройств хранят сведения об устройствах:
Приложения устройств и внутренние приложения могут использовать для синхронизации условий и конфигурации устройств.
Серверная часть решения может использовать их для выполнения запроса и указания длительных операций.
Жизненный цикл двойника устройства связан с соответствующим удостоверением устройства. Двойники устройства неявно создаются и удаляются при создании или удалении удостоверения устройства в Центре Интернета вещей.
Двойник устройства является документом JSON, содержащим следующие компоненты:
Теги. Раздел документа JSON, в который внутренние приложения могут считывать и записывать данные. Теги не видны приложениям устройств.
Требуемые свойства. Используются совместно с сообщаемыми свойствами для синхронизации конфигурации или условий устройства. Внутренние приложения могут задавать нужные свойства, а приложение устройства может читать их. Приложение устройства может также получать уведомления об изменениях в нужных свойствах.
Сообщаемые свойства. Используется совместно с требуемыми свойствами для синхронизации конфигурации или условий устройства. Приложение устройства может задавать сообщаемые свойства, а внутренние приложения могут читать и запрашивать их.
Свойства удостоверений устройств. Корень документа JSON двойника устройства содержит свойства только для чтения из соответствующего удостоверения устройства, хранимые в реестре удостоверений.
generationIdСвойстваconnectionStateUpdatedTimeи свойства не включены.
Ниже приведен пример документа JSON двойника устройства:
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
Корневой объект содержит свойства удостоверения устройства, а также объекты контейнера для tags обоих и reported desired свойств. Контейнер properties содержит некоторые элементы только для чтения ($metadata и $version), описанные в разделах Метаданные двойника устройства и Оптимистичный параллелизм.
Пример сообщаемых свойств
В предыдущем примере двойник устройства содержит batteryLevel сообщаемое свойство. Это свойство позволяет выполнить запрос и работать на устройствах на основе последних сообщенных сведений об уровне заряда аккумулятора. Другой пример: приложение устройства сообщает о возможностях и вариантах подключения устройства.
Примечание.
Сообщаемые свойства упрощают сценарии, в которых вы заинтересованы в последнем известном значении свойства. Используйте сообщения с устройства в облако, если вы хотите обработать данные телеметрии устройства в виде последовательностей событий метки времени, таких как временные ряды.
Пример требуемого свойства
В предыдущем примере требуемые и сообщаемые свойства двойника устройства telemetryConfig используются в серверной части решения и приложении для устройства, чтобы синхронизировать конфигурацию телеметрии для этого устройства. Например:
Серверное приложение задает требуемое свойство с требуемым значением конфигурации. Ниже приведена часть документа с требуемым набором свойств:
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },Приложение устройства немедленно получает извещение об изменении, если устройство подключено. Если оно не подключено, то при подключении приложение устройства использует поток повторного подключения устройства. Затем приложение устройства сообщает об обновленной конфигурации (или об условии ошибки с помощью свойства
status). Ниже приведена часть сообщаемых свойств:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }Серверное приложение отслеживает результаты операции конфигурации на многих устройствах путем запроса двойников устройств.
Примечание.
Предыдущие фрагменты являются примерами способа кодирования конфигурации устройства и его состояния, оптимизированными для удобства чтения. Центр Интернета вещей не использует специальную схему для требуемых и сообщаемых свойств в двойниках устройств.
Внимание
IoT Plug and Play определяет схему, которая использует несколько дополнительных свойств для синхронизации изменений требуемых и сообщаемых свойств. Если решение использует IoT Plug and Play, необходимо следовать соглашениям Plug and Play при обновлении свойств двойников. Дополнительные сведения и пример см. в разделе Записываемые свойства в IoT Plug and Play.
Двойники используются для синхронизации длительных операций, например обновления встроенного ПО. Дополнительные сведения о синхронизации и отслеживании длительных операций на устройствах с помощью свойств см. в статье Настройка устройств с помощью требуемых свойств (Node).
Операции серверной части
Серверная часть решения выполняет действия в двойнике устройства с помощью следующих атомарных операций, доступных по протоколу HTTPS:
Получение двойника устройства по идентификатору. Эта операция возвращает документ двойника устройства, включая теги, а также требуемые и сообщаемые системные свойства.
Частичное обновление двойника устройства. Эта операция частично обновляет теги или требуемые свойства в двойнике устройства. Частичное обновление выражается в качестве документа JSON, который добавляет или обновляет все свойства. Свойства, для которых указано значение
null, удаляются. Следующий пример создает требуемое свойство со значением{"newProperty": "newValue"}, перезаписывает существующее значениеexistingPropertyна"otherNewValue"и удаляетotherOldProperty. Другие существующие требуемые свойства или теги не изменяются:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Заменить требуемые свойства. Эта операция полностью перезаписывает все существующие требуемые свойства и заменяет новый документ JSON для
properties/desired.Заменить теги. Эта операция полностью перезаписывает все существующие теги и заменяет новый документ JSON для
tags.Получение уведомлений двойника. Эта операция уведомляет об изменении двойника. Чтобы получать уведомления об изменении двойника устройства, решение Интернета вещей должно создать маршрут и задать источник данных равным twinChangeEvents. По умолчанию такие маршруты не существуют, поэтому уведомления двойника не отправляются. Если скорость изменения слишком высока или имеются какие-либо другие причины (например, внутренние сбои), Центр Интернета вещей может отправлять только одно уведомление, которое содержит все изменения. Таким образом, если приложению требуется надежный аудит и регистрация всех промежуточных состояний, следует использовать сообщения, отправляемые с устройства в облако. Дополнительные сведения о свойствах и теле, возвращаемых в сообщении уведомления о двойниках, см. в разделах схемы событий Nontelemetry.
Все предыдущие операции поддерживают оптимистичный параллелизм и требуют разрешения ServiceConnect, как указано в статье Управление доступом к Центру Интернета вещей.
Помимо выполнения этих операций серверная часть решений может:
отправлять запросы к двойникам устройств с помощью языка запросов Центра Интернета вещей типа SQL;
выполнять операции с большими наборами двойников устройств с помощью заданий.
Операции с устройствами
Приложение устройства выполняет действия в двойнике устройства с помощью следующих атомарных операций.
Получение двойника устройства. Эта операция возвращает документ двойника (включая требуемые и сообщаемые системные свойства) для подключенного устройства. (Теги не видны приложениям устройств.)
Частично обновить сообщаемые свойства. Эта операция позволяет частично обновить сообщаемые свойства подключенного устройства.
Отслеживать требуемые свойства. Для подключенного устройства можно настроить немедленное получение уведомлений об обновлениях нужного свойства в момент такого обновления.
Все предыдущие операции требуют разрешения DeviceConnect, как указано в статье Управление доступом к Центру Интернета вещей.
Пакеты SDK для устройств Azure IoT упрощают использование указанных выше операций на многих языках и платформах. Дополнительные сведения о примитивах Центра Интернета вещей для синхронизации требуемых свойств см. в разделе Процедура при повторном подключении устройства.
Формат тегов и свойств
Теги, а также требуемые и сообщаемые свойства являются объектами JSON, на которые накладываются следующие ограничения.
Ключи. Все ключи в объектах JSON используются в кодировке UTF-8 с учетом регистра и имеют размер до 1 КБ. Разрешено использовать все знаки, кроме управляющих знаков Юникода (сегменты C0 и C1), а также
.,$и SP.Примечание.
Запросы Центра Интернета вещей, используемые в маршрутизации сообщений, не поддерживают пробелы или любые из следующих символов в составе имени ключа:
()<>@,;:\"/?={}.Значения. Все значения в объектах JSON могут относиться к следующим типам JSON: логический, число, строка и объект. Также поддерживаются массивы.
Целые числа могут иметь минимальное значение –4503599627370496 и максимальное значение 4503599627370495.
Для строковых значений используется кодировка UTF-8, их максимальная длина составляет 4 КБ.
Глубина. Максимальная глубина объектов JSON в тегах, требуемых и сообщаемых свойствах равна 10. Например, следующий объект является допустимым:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Размер двойника устройства
Центр Интернета вещей применяет ограничение размера 8 КБ для значения tagsи ограничение размера 32 КБ для каждого значения properties/desired и properties/reported. Эти итоговые данные относятся исключительно к элементам, доступным только для чтения, например $version и $metadata/$lastUpdated.
Размер двойника вычисляется следующим образом:
Центр Интернета вещей совокупно вычисляет и добавляет длину ключа и значения каждого свойства.
Ключи свойств рассматриваются как строки в кодировке UTF8.
Значения простых свойств рассматриваются как строки в кодировке UTF-8, числовые значения (8 байт) или логические значения (4 байта).
Размер вычисляется путем подсчета всех знаков с кодировкой UTF-8, кроме управляющих символов Юникода (сегменты C0 и C1).
Значения сложных свойств (вложенные объекты) вычисляются на основе статистического размера ключей свойств и значений свойств, которые они содержат.
Центр Интернета вещей отклоняет с ошибкой все операции, которые увеличивают размер документов tags, properties/desired и properties/reported выше заданного ограничения.
Метаданные двойника устройства
Центр Интернета вещей сохраняет метку времени последнего обновления для каждого объекта JSON в требуемых и сообщаемых свойствах двойника устройства. Метки времени указываются в формате UTC и кодируются в формате ISO8601 (YYYY-MM-DDTHH:MM:SS.mmmZ).
Например:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
Эти сведения хранятся на каждом уровне (а не только в конечных элементах структуры JSON) для сохранения обновлений, удаляющих ключи объекта.
Оптимистическая блокировка
Теги, а также требуемые и сообщаемые свойства поддерживают оптимистичный параллелизм. Если вам нужно обеспечить определенный порядок обновлений свойств двойника, попробуйте реализовать синхронизацию на уровне приложения путем ожидания обратного вызова сообщаемых свойств перед отправкой следующего обновления.
Двойники устройств имеют свойство etagETag, как по RFC7232, представляющее представление JSON двойника. Свойство etag можно использовать в операциях условного обновления в серверной части решения, чтобы обеспечить согласованность. Это свойство является единственным вариантом обеспечения согласованности в операциях, связанных с контейнером tags .
В требуемых и сообщаемых свойствах двойника устройства также содержится значение $version, которое гарантированно будет добавочным. Аналогично ETag, можно использовать свойство версии для обеспечения согласованности обновлений. Например, приложение устройства для сообщаемого свойства или серверного приложения для требуемого свойства.
Версии также полезны, если агент, выполняющий отслеживание (например, приложение устройства, отслеживающее требуемые свойства), должен устранить состояние гонки между результатом извлечения и отправкой уведомлений об обновлении. Дополнительные сведения см. в разделе Процедура при повторном подключении устройства.
Процедура при повторном подключении устройства
Центр Интернета вещей не сохраняет уведомления об обновлении нужных свойств для отключенных устройств. Это значит, что подключающееся устройство должно получить весь документ требуемых свойств и подписаться на уведомления об обновлениях. Учитывая возможность возникновения состояния гонки между уведомлениями об обновлениях и полным извлечением, следуйте процедуре ниже:
- Приложение устройства подключается к Центру Интернета вещей.
- Приложение устройства подписывается на уведомления об обновлениях требуемых свойств.
- Приложение устройства получает весь документ требуемых свойств.
Приложение устройства может игнорировать все уведомления со значением $version, которое меньше значения версии полного полученного документа или равно ему. Такой подход возможен, так как Центр Интернета вещей гарантирует постоянное увеличение версий.
Следующие шаги
Дополнительные сведения о некоторых понятиях, описанных в этой статье, см. в следующих статьях Центр Интернета вещей: