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

Статья
02/22/2024

Двойники устройств — это документы JSON, хранящие сведения о состоянии устройства, в том числе метаданные, конфигурации и условия. Центр Интернета вещей Azure сохраняет двойник устройства для каждого устройства, подключаемого к Центру Интернета вещей.

Примечание.

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

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

Структура двойника устройства: теги, требуемые свойства и сообщаемые свойства.
Операции, выполняемые устройствами и внутренними приложениями, могут выполняться в двойниках устройств.

Двойники устройства используются для выполнения следующих действий:

Хранение метаданных для конкретного устройства в облаке. Например, расположение виртуального компьютера.
Сообщение сведений о текущем состоянии приложения устройства, таких как доступные возможности и условия. Например, подключение устройства к центру Интернета вещей по сети мобильной связи или Wi-Fi.
Синхронизация состояния длительных рабочих процессов между приложением устройства и внутренним приложением. Например, при указании новой версии встроенного ПО в серверной части решения и сообщении различных этапов процесса обновления в приложении для устройства.
выполнение запроса метаданных, конфигурации или состояния устройства.

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

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

Сведения о том, как двойники устройства связаны с моделью, используемой устройством Azure IoT Plug and Play, см. в статье Общие сведения о цифровых двойниках устройств IoT Plug and Play.

Двойники устройств

Двойники устройств хранят сведения об устройствах:

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

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

Двойник устройства является документом JSON, содержащим следующие компоненты:

Теги. Раздел документа JSON, который может считывать и в который может выполнять запись серверная часть решения. Теги не видны приложениям устройств.
Требуемые свойства. Используются совместно с сообщаемыми свойствами для синхронизации конфигурации или условий устройства. В серверной части решения можно задать нужные свойства, а приложение устройства может считывать их. Приложение устройства может также получать уведомления об изменениях в нужных свойствах.
Сообщаемые свойства. Используется совместно с требуемыми свойствами для синхронизации конфигурации или условий устройства. Приложение устройства может задать сообщаемые свойства, а серверная часть решения может считывать и запрашивать их.
Свойства удостоверений устройств. Корень документа JSON двойника устройства содержит свойства только для чтения из соответствующего удостоверения устройства, хранимые в реестре удостоверений. Свойства connectionStateUpdatedTime и generationId не будут включены.

Diagram that shows which applications interact with which device twin properties.

Ниже приведен пример документа 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 обоих и reporteddesired свойств. Контейнер 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;
выполнять операции с большими наборами двойников устройств с помощью заданий.

Операции с устройствами

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

Получение двойника устройства. Эта операция возвращает документ двойника (включая требуемые и сообщаемые системные свойства) для подключенного устройства. (Теги не видны приложениям устройств.)
Частично обновить сообщаемые свойства. Эта операция позволяет частично обновить сообщаемые свойства подключенного устройства. В этой операции используется тот же формат обновления JSON, как и при частичном обновлении требуемых свойств в серверной части решения.
Отслеживать требуемые свойства. Для подключенного устройства можно настроить немедленное получение уведомлений об обновлениях нужного свойства в момент такого обновления. Устройство выполняет такое же обновление (частичное обновление или полная замена), как и при выполнении в серверной части решения.

Все предыдущие операции требуют разрешения 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.

Размер двойника вычисляется следующим образом:

Для каждого свойства в документе JSON центр Интернета вещей кумулятивно вычисляет и добавляет длину ключа и значение свойства.
Ключи свойств рассматриваются как строки в кодировке 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) для сохранения обновлений, удаляющих ключи объекта.

Оптимистическая блокировка

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

Двойники устройств содержат ETag (свойство etag), согласно RFC7232, являющийся представлением JSON двойника. Свойство etag можно использовать в операциях условного обновления в серверной части решения, чтобы обеспечить согласованность. Это единственный вариант обеспечения согласованности для операций с контейнером tags.

В требуемых и сообщаемых свойствах двойника устройства также содержится значение $version, которое гарантированно будет добавочным. Аналогично ETag для обеспечения согласованности обновлений компонент, выполняющий обновление, использует версию. Например, приложение устройства для сообщаемого свойства или серверная сторона для требуемого свойства.

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

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

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

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

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

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

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

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

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

Двойники устройств

Пример сообщаемых свойств

Пример требуемого свойства

Операции серверной части

Операции с устройствами

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

Размер двойника устройства

Метаданные двойника устройства

Оптимистическая блокировка

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

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

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