Общие сведения и использование двойников модулей в Центре Интернета вещей

В IoT-хабе, под каждым идентификатором устройства, можно создать до 50 идентификаторов модулей. Каждый идентификатор модуля неявно создает двойник модуля. Как и двойники устройств, двойники модулей — это документы JSON, в которых хранятся сведения о состоянии модуля, включая метаданные, конфигурации и условия. Центр Интернета вещей Azure поддерживает двойник модуля для каждого модуля, подключаемого к Центру Интернета вещей.

Предполагается, что вы сначала прочитали “Изучение и использование двойников устройств в IoT Hub”.

На стороне устройства комплекты SDK для разработки программного обеспечения IoT Hub позволяют создавать модули, в каждом из которых открывается независимое подключение к IoT Hub. Эта функция позволяет использовать отдельные пространства имен для различных компонентов на устройстве. Например, у вас есть торговый автомат с тремя разными датчиками. Различные отделы в вашей компании контролируют каждый датчик. Вы можете создать модуль для каждого датчика, чтобы отдел мог отправлять задания или направлять методы на датчик, который они контролируют, избегая конфликтов и ошибок пользователей.

Удостоверение модуля и двойник модуля предоставляют те же возможности, что и удостоверение устройства и двойник устройства, но при более детальной детализации. Эта более подробная детализация позволяет устройствам, таким как устройства на основе операционной системы или устройства встроенного ПО, которые управляют несколькими компонентами, изолировать конфигурацию и условия для каждого из этих компонентов. Идентификация модуля и двойники модулей обеспечивают управленческое разделение ответственностей при работе с устройствами Интернета вещей с модульными программными компонентами. Мы стремимся поддерживать все функциональные возможности двойников устройств на уровне двойника модуля по общедоступной доступности двойника модуля.

Примечание

Функции, описанные в этой статье, доступны только на стандартном уровне Центра Интернета вещей. Дополнительные сведения о базовых и стандартных и бесплатных уровнях Центра Интернета вещей см. в разделе Выберите нужный уровень и размер Центра Интернета вещей для вашего решения.

В этой статье рассматриваются следующие вопросы:

Инструкции по обмену данными между устройствами и облаком см. в руководстве по использованию сообщаемых свойств, сообщений устройства в облако или отправки файлов.

Инструкции по обмену данными между облаком и устройствами см. в руководстве по использованию нужных свойств, прямых методов или сообщений между устройствами.

Двойники модулей

Двойники модулей хранят сведения, связанные с модулем, которые:

  • Модули на устройстве и IoT Hub могут быть использованы для синхронизации состояния модуля и конфигурации.

  • Бэкенд решения можно использовать для выполнения запросов к длительным операциям и их обработки.

Жизненный цикл двойника модуля связан с соответствующей идентификацией модуля. Двойники модулей неявно создаются и удаляются при создании или удалении удостоверения модуля в Центре Интернета вещей.

Двойник модуля — это документ JSON, который включает в себя:

  • Tags. Раздел документа 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 используются серверными приложениями и приложением модуля для синхронизации конфигурации телеметрии для этого модуля. Рассмотрим пример.

  1. Серверное приложение задает требуемое свойство с требуемым значением конфигурации. Ниже приведена часть документа с требуемым набором свойств:

    ...
"desired": {
    "telemetryConfig": {
        "sendFrequency": "5m"
    },
    ...
},
...

  2. Приложение модуля немедленно уведомляется об изменении, если модуль подключен. Если оно не подключено, приложение модуля следует потоку повторного подключения модуля при подключении. Затем приложение модуля сообщает обновленную конфигурацию (или условие ошибки с помощью status свойства). Ниже приведена часть сообщаемых свойств:

    "reported": {
    "telemetryConfig": {
        "sendFrequency": "5m",
        "status": "success"
    }
    ...
}

  3. Серверное приложение может отслеживать результаты операции конфигурации во многих модулях, запрашивая двойники модулей.

Примечание

Предыдущие фрагменты кода являются примерами, оптимизированными для удобства чтения, одним из способов кодирования конфигурации модуля и его состояния. Центр Интернета вещей не накладывает определенную схему для нужного двойника модуля и сообщает о свойствах в двойниках модуля.

Важно

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, IoT Hub.

Операции модуля

Приложение модуля работает с двойником модуля с помощью следующих атомарных операций:

  • Получение модуля-двойника. Эта операция возвращает документ двойника модуля (включая требуемые и сообщаемые системные свойства) для подключенного модуля.

  • Частично обновите сообщаемые свойства. Эта операция обеспечивает частичное обновление сообщаемых свойств подключенного модуля.

  • Наблюдайте за нужными свойствами. Подключенный модуль может получать уведомления об обновлениях желаемых свойств в момент их появления.

Для всех предыдущих операций требуется разрешение DeviceConnect , как определено в статье "Контроль доступа к Центру Интернета вещей".

Пакеты SDK для устройств Интернета вещей Azure упрощают использование предыдущих операций со многих языков и платформ.

Формат тегов и свойств

Теги, требуемые свойства и сообщаемые свойства — это объекты JSON со следующими ограничениями:

  • Ключи: Все ключи в объектах JSON закодированы в UTF-8, чувствительны к регистру и имеют длину до 1 КБ. Допустимые символы исключают управляющие символы ЮНИКОД (сегменты C0 и C1), а также ., $, и SP.

  • Значения: все значения в объектах JSON могут иметь следующие типы JSON: boolean, number, string, object. Также поддерживаются массивы.

    • Целые числа могут иметь минимальное значение -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.

  • Простые значения свойств считаются строками в кодировке UTF8, числовыми значениями (8 Байт) или логическими значениями (4 Байт).

  • Размер строк в кодировке UTF8 вычисляется путем подсчета всех символов, за исключением символов элемента управления ЮНИКОД (сегменты C0 и C1).

  • Сложные значения свойств (вложенные объекты) вычисляются на основе совокупного размера ключей и значений свойств, которые они содержат.

Центр Интернета вещей отклоняет с ошибкой все операции, которые увеличат размер этих документов и таким образом превышают предел.

Метаданные двойника модуля

Центр Интернета вещей поддерживает метку времени последнего обновления для каждого объекта JSON в нужном и сообщаемом свойстве двойника модуля. Метки времени находятся в формате UTC и кодируются в формате 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, можно использовать значение версии для обеспечения согласованности обновлений. Например, модульное приложение для зарегистрированного свойства или серверное приложение для желаемого свойства.

Версии также полезны, если агент наблюдения (например, приложение модуля, наблюдающее за требуемыми свойствами) должен разрешать конфликты между результатом операции извлечения и уведомлением об обновлении. Раздел поток повторного подключения модуля предоставляет дополнительные сведения.

Поток повторного подключения модуля

Центр Интернета вещей не сохраняет уведомления об обновлении нужных свойств для отключенных модулей. Ниже показано, что модуль, который подключается, должен получить полный документ необходимых свойств, помимо подписки на уведомления об обновлении. Учитывая возможность конкуренции между уведомлениями об обновлениях и полным извлечением, необходимо обеспечить следующий процесс:

  1. Приложение модуля подключается к Центру Интернета вещей.
  2. Приложение модуля подписывается на уведомления об обновлении нужных свойств.
  3. Приложение модуля извлекает полный документ для требуемых свойств.

Приложение модуля может игнорировать все уведомления с $version, если они меньше или равны версии полностью извлеченного документа. Этот подход возможен, так как Центр Интернета вещей гарантирует, что версии всегда увеличиваются.

Дальнейшие действия

Сведения о некоторых понятиях, описанных в этой статье, см. в следующих руководствах по Центру Интернета вещей:

  • Last updated on