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

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

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.

• Получение уведомлений двойника. Эта операция позволяет серверной части решения получать уведомления при изменении двойника. Для этого в решении Интернета вещей необходимо создать маршрут и присвоить источнику данных значение twinChangeEvents. По умолчанию такие маршруты не существуют, поэтому уведомления двойника не отправляются. Если скорость изменения слишком высока или имеются какие-либо другие причины (например, внутренние сбои), Центр Интернета вещей может отправлять только одно уведомление, которое содержит все изменения. Таким образом, если приложению требуется надежный аудит и регистрация всех промежуточных состояний, следует использовать сообщения, отправляемые с устройства в облако. Дополнительные сведения о свойствах и тексте, возвращаемых в уведомлении двойника, см. в разделе Схемы нетелеметрических событий.

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

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

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

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

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

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

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

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

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

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

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

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

• Приступая к работе с удостоверением Центра Интернета вещей и двойником модуля с использованием серверной части и устройства .NET