Общие сведения о двойниках модулей и их использование в Центре Интернета вещей
В Центре Интернета вещей для каждого удостоверения устройства можно создать до 50 удостоверений модулей. Каждое удостоверение модуля неявно создает двойник модуля. Аналогично двойникам устройств двойники модулей — это документы JSON, хранящие сведения о состоянии модуля, в том числе метаданные, конфигурации и условия. Центр Интернета вещей Azure сохраняет двойник модуля для каждого модуля, подключаемого к Центру Интернета вещей.
В этой статье предполагается, что сначала вы узнаете и используете двойники устройств в Центр Интернета вещей.
На стороне устройства Центр Интернета вещей комплекты средств разработки программного обеспечения устройств (SDK) позволяют создавать модули, в которых каждый открывает независимое подключение к Центр Интернета вещей. Благодаря этим возможностям вы можете использовать отдельные пространства имен для разных компонентов на устройстве. Например, у вас есть торговый автомат с тремя разными датчиками. Различные отделы в вашей компании контролируют каждый датчик. Вы можете создать модуль для каждого датчика, чтобы отдел мог отправлять задания или направлять методы на датчик, который они контролируют, избегая конфликтов и ошибок пользователей.
Удостоверение и двойник модуля предоставляют те же возможности, что и удостоверение и двойник устройства, но с большей степенью детализации. Благодаря этому совместимые устройства, например устройства на основе операционной системы или устройства со встроенным ПО, которые управляют несколькими компонентами, могут изолировать конфигурацию и условия для каждого из этих компонентов. Удостоверение модуля и двойники модулей позволяют разделить управление вопросами при работе с устройствами Интернета вещей с модульными программными компонентами. Наша цель — предоставить поддержку всем функциям двойников устройств на уровне двойника модуля с помощью общедоступной версии двойника устройств.
Примечание.
Функции, описанные в этой статье, доступны только на стандартном уровне Центра Интернета вещей. Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.
В этой статье рассматриваются следующие вопросы:
- структура двойника модуля: теги, требуемые и сообщаемые свойства;
- Операции, выполняемые приложениями устройств и внутренней частью решения, могут выполняться в двойниках модулей.
Руководство по использованию сообщаемых свойств, сообщений, отправляемых с устройства в облако, или передаче файла см. в статье Руководство по обмену данными между устройством и облаком.
Руководство по использованию требуемых свойств, прямых методов или сообщений, отправляемых из облака на устройство, см. в статье Руководство по обмену данными между облаком и устройством.
Двойники модулей
Двойники модулей хранят сведения о модулях:
Модули устройства и Центр Интернета вещей могут использовать их для синхронизации условий и конфигурации модуля.
Серверная часть решения может использовать их для выполнения запроса и указания длительных операций.
Жизненный цикл двойника модуля связан с соответствующим удостоверением модуля. Двойники модуля неявно создаются и удаляются при создании или удалении удостоверения модуля в Центре Интернета вещей.
Двойник модуля является документом JSON, содержащим следующие компоненты:
Теги. Раздел документа JSON, в который внутренние приложения могут считывать и записывать данные. Теги не видны модулям на устройстве. Теги задаются для выполнения запросов.
Требуемые свойства. Используются совместно с сообщаемыми свойствами для синхронизации конфигурации или условий модуля. Внутренние приложения могут задавать нужные свойства, а приложение модуля может читать их. Приложение модуля может также получать уведомления об изменениях в нужных свойствах.
Сообщаемые свойства. Используется совместно с требуемыми свойствами для синхронизации конфигурации или условий модуля. Приложение модуля может задавать сообщаемые свойства, а внутренние приложения могут читать и запрашивать их.
Свойства удостоверений модулей. Корень документа JSON двойника модуля содержит свойства только для чтения из соответствующего удостоверения модуля, хранимые в реестре удостоверений.
Ниже приведен пример документа JSON двойника модуля:
{
"deviceId": "devA",
"moduleId": "moduleA",
"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.
Операции серверной части
Серверные приложения работают с двойником модуля с помощью следующих атомарных операций, предоставляемых через HTTPS:
Получение двойника модуля по идентификатору. Эта операция возвращает документ двойника модуля, включая теги, а также требуемые и сообщаемые системные свойства.
Частичное обновление двойника модуля. Эта операция частично обновляет теги или требуемые свойства в двойнике модуля. Частичное обновление выражается в качестве документа JSON, который добавляет или обновляет все свойства. Свойства, для которых указано значение
null, удаляются. Следующий пример создает требуемое свойство со значением{"newProperty": "newValue"}, перезаписывает существующее значениеexistingPropertyна"otherNewValue"и удаляетotherOldProperty. Другие существующие требуемые свойства или теги не изменяются:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Заменить требуемые свойства. Эта операция полностью перезаписывает все существующие требуемые свойства и заменяет новый документ JSON для
properties/desired.Заменить теги. Эта операция полностью перезаписывает все существующие теги и заменяет новый документ JSON для
tags.Получение уведомлений двойника. Эта операция уведомляет об изменении двойника. Чтобы получать уведомления об изменении двойника модуля, решение Интернета вещей должно создать маршрут и задать источник данных равным twinChangeEvents. По умолчанию такие маршруты не существуют, поэтому уведомления двойника не отправляются. Если скорость изменения слишком высока или имеются какие-либо другие причины (например, внутренние сбои), Центр Интернета вещей может отправлять только одно уведомление, которое содержит все изменения. Таким образом, если приложению требуется надежный аудит и регистрация всех промежуточных состояний, следует использовать сообщения, отправляемые с устройства в облако. Дополнительные сведения о свойствах и тексте, возвращаемых в уведомлении двойника, см. в разделе Схемы нетелеметрических событий.
Все предыдущие операции поддерживают оптимистичный параллелизм и требуют разрешения 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).
Значения сложных свойств (вложенные объекты) вычисляются на основе статистического размера ключей свойств и значений свойств, которые они содержат.
Центр Интернета вещей отклоняет с ошибкой все операции, увеличивающие размер этих документов сверх ограничения.
Метаданные двойника модуля
Центр Интернета вещей сохраняет метку времени последнего обновления для каждого объекта 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": "5m",
"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) для сохранения обновлений, удаляющих ключи объекта.
Оптимистическая блокировка
Теги, а также требуемые и сообщаемые свойства поддерживают оптимистичный параллелизм. Если вам нужно обеспечить определенный порядок обновлений свойств двойника, попробуйте реализовать синхронизацию на уровне приложения путем ожидания обратного вызова сообщаемых свойств перед отправкой следующего обновления.
Двойники модулей содержат ETag (свойство etag), согласно RFC7232, являющийся представлением JSON двойника. Свойство можно использовать etag в операциях условного обновления из внутренних приложений, чтобы обеспечить согласованность. Этот параметр обеспечивает согласованность операций, связанных с контейнером tags .
В требуемых и сообщаемых свойствах двойника модуля также содержится значение $version, которое гарантированно будет добавочным. Аналогично ETag, можно использовать значение версии для обеспечения согласованности обновлений. Например, приложение модуля для сообщаемого свойства или серверного приложения для требуемого свойства.
Версии также полезны, если агент, выполняющий отслеживание (например, приложение модуля, отслеживающее требуемые свойства), должен устранить состояние гонки между результатом извлечения и отправкой уведомлений об обновлении. Дополнительные сведения см. в разделе Процедура при повторном подключении модуля.
Процедура при повторном подключении модуля
Центр Интернета вещей не сохраняет уведомления об обновлении нужных свойств для отключенных модулей. Это значит, что подключающийся модуль должен получить весь документ требуемых свойств и подписаться на уведомления об обновлениях. Учитывая возможность возникновения состояния гонки между уведомлениями об обновлениях и полным извлечением, следуйте процедуре ниже:
- Приложение модуля подключается к Центру Интернета вещей.
- Приложение модуля подписывается на уведомления об обновлениях требуемых свойств.
- Приложение модуля получает весь документ требуемых свойств.
Приложение модуля может игнорировать все уведомления со значением $version, которое меньше значения версии полного полученного документа или равно ему. Такой подход возможен, так как Центр Интернета вещей гарантирует постоянное увеличение версий.
Следующие шаги
Чтобы применить некоторые основные понятия, описанные в этой статье, просмотрите следующие руководства по Центру Интернета вещей: