Изучите и используйте двойники устройств в узле IoT

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

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

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

Используйте двойники устройств для:

• Хранение метаданных для конкретного устройства в облаке. Например, расположение торгового автомата.

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

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

• Запрос метаданных, конфигурации или состояния устройства.

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

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

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

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

Двойники устройств хранят информацию об устройствах:

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

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

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

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

• Теги. Раздел документа JSON, в который внутренние приложения могут считывать и записывать данные. Теги не видны приложениям устройств.

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

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

• Свойства идентификационных данных устройств Корень документа JSON двойника устройства содержит свойства только для чтения из соответствующего удостоверения устройства, хранимые в реестре удостоверений. Свойства connectionStateUpdatedTime и generationId не включены.

Ниже приведен пример документа 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 используются в серверной части решения и приложении для устройства, чтобы синхронизировать конфигурацию телеметрии для этого устройства. Например:

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

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

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

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

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

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

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

Серверная часть решения выполняет действия на двойнике устройства с помощью следующих атомарных операций, доступных по протоколу HTTPS.

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

• Частичное обновление цифрового двойника устройства. Эта операция частично обновляет теги или требуемые свойства в двойнике устройства. Частичное обновление выражается в качестве документа JSON, который добавляет или обновляет все свойства. Свойства, для которых указано значение null, удаляются. Следующий пример создает требуемое свойство со значением {"newProperty": "newValue"}, перезаписывает существующее значение existingProperty на "otherNewValue" и удаляет otherOldProperty. Другие существующие требуемые свойства или теги не изменяются:

  {
       "properties": {
           "desired": {
               "newProperty": {
                   "nestedProperty": "newValue"
               },
               "existingProperty": "otherNewValue",
               "otherOldProperty": null
           }
       }
  }
  

• Заменить требуемые свойства. Эта операция полностью перезаписывает все существующие требуемые свойства и заменяет новый документ JSON для properties/desired.

• Заменить теги. Эта операция полностью перезаписывает все существующие теги и заменяет новый документ JSON для tags.

• Получение двойных уведомлений. Эта операция уведомляет об изменении цифрового двойника. Чтобы получать уведомления об изменении двойника устройства, IoT-решение должно создать маршрут и установить источник данных равным 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, можно использовать свойство версии для обеспечения согласованности обновлений. Например, приложение устройства для сообщаемого свойства или серверного приложения для требуемого свойства.

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

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

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

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

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

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

Чтобы попробовать некоторые из концепций, описанных в этой статье, ознакомьтесь со следующими статьями о IoT Hub:

• Руководство: Настройка устройств с помощью свойств цифровых двойников
• Использование двойников устройств