Создание и чтение сообщений Центра Интернета вещей
Для поддержки взаимодействия между протоколами Центр Интернета вещей определяет общий набор функций обмена сообщениями, доступных во всех протоколах, подключенных к устройству. Эти функции можно использовать как в сообщениях между устройствами, так и в сообщениях из облака на устройство.
Примечание.
Некоторые функции, упоминаемые в этой статье, например обмен сообщениями между облаком и устройством, двойники устройств и управление устройствами, доступны только для Центра Интернета вещей уровня "Стандартный". Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.
Для реализация отправки сообщений с устройства в облако Центр Интернета вещей использует модель потоковой передачи сообщений. сообщения Центр Интернета вещей устройства в облако больше похожи наСобытия Центров событий, чем служебная шина сообщения, в том, что существует большой объем событий, передаваемых через службу, которую может прочитать несколько читателей.
Сообщение Центра Интернета вещей состоит из следующих компонентов.
Предопределенный набор системных свойств , как описано далее в этой статье.
Набор свойств приложения. Словарь свойств строки, которые приложение может задать и использовать без необходимости десериализации текста сообщения. Центр Интернета вещей никогда не изменяет эти свойства.
Текст сообщения, который может быть любым типом данных.
Каждый протокол устройства реализует свойства параметров различными способами. Дополнительные сведения см. в руководстве разработчика по протоколу MQTT и руководстве по протоколу AMQP.
При отправке сообщений с устройства в облако с помощью протокола HTTPS или отправки сообщений из облака в устройство имена свойств и значения могут содержать только буквенно-цифровые символы ASCII, а также ! # $ % & ' * + - . ^ _ ` | ~ .
Отправка сообщений с устройства в облако с помощью Центра Интернета вещей имеет следующие характеристики:
Сообщения, отправляемые с устройства в облако, устойчивы и хранятся в конечной точке по умолчанию messages/events Центра Интернета вещей до семи дней.
Размер сообщений, поступающих с устройства в облако, не может превышать 256 КБ, и их можно объединять в пакеты, чтобы оптимизировать отправку. Размер пакетов не может превышать 256 КБ.
Центр Интернета вещей не допускает произвольное секционирование. Сообщения, отправляемые с устройства в облако, секционируются по исходному идентификатору deviceId.
Как поясняется в статье Управление доступом к Центру Интернета вещей, Центр Интернета вещей обеспечивает аутентификацию и контроль доступа для каждого устройства.
Можно пометить сообщения данными, которые будут передаваться в свойства приложения. Дополнительные сведения см. в статье Обогащение сообщений.
Примечание.
Каждый протокол Центра Интернета вещей предоставляет свойство типа контента сообщения, которое учитывается при маршрутизации данных в пользовательские конечные точки. Чтобы данные правильно обрабатывались в месте назначения (например, JSON, обрабатываемый как строка синтаксического анализа вместо двоичных данных в кодировке Base64), укажите соответствующий тип контента и набор символов для сообщения.
Чтобы использовать текст сообщения в запросе маршрутизации Центр Интернета вещей, укажите допустимый объект JSON для сообщения и задайте для свойства типа контента сообщения application/json;charset=utf-8значение .
В следующем примере показан допустимый, маршрутизируемый текст сообщения:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Системные свойства сообщений из устройства в облако
| Свойство | Description | Задается пользователем? | Ключевое слово для запроса маршрутизации |
|---|---|---|---|
| message-id | Задаваемый пользователем идентификатор сообщения, используемый для шаблонов типа "запрос-ответ". Формат: строка с учетом регистра (до 128 символов длиной) 7-разрядных буквенно-цифровых символов ASCII плюс - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Да | messageId |
| iothub-enqueuedtime | Дата и время получения сообщения, отправленного с устройства в облако, Центром Интернета вещей. | No | enqueuedTime |
| user-id | Идентификатор, используемый для указания источника сообщений. | Да | userId |
| iothub-connection-device-id | Центр Интернета вещей устанавливает этот идентификатор в сообщениях, отправляемых с устройства в облако. Содержит идентификатор deviceId устройства, отправившего сообщение. | No | connectionDeviceId |
| iothub-connection-module-id | Центр Интернета вещей устанавливает этот идентификатор в сообщениях, отправляемых с устройства в облако. Содержит идентификатор moduleId устройства, с которого было отправлено сообщение. | No | connectionModuleId |
| iothub-connection-auth-generation-id | Центр Интернета вещей устанавливает этот идентификатор в сообщениях, отправляемых с устройства в облако. Содержит идентификатор generationId устройства, с которого было отправлено сообщение (согласно разделу Свойства удостоверений устройств). | No | connectionDeviceGenerationId |
| iothub-connection-auth-method | Центр Интернета вещей устанавливает этот метод проверки подлинности в сообщениях, отправляемых с устройства в облако. Это свойство содержит сведения о методе проверки подлинности, используемом для аутентификации устройства, отправляющего сообщение. | No | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Разрешает устройству отправлять время создания события при отправке данных в пакет. | Да | creation-time-utc |
| iothub-creation-time-utc | Разрешает устройству отправлять время создания события при отправке одного сообщения за раз. | Да | creation-time-utc |
| dt-dataschema | Центр Интернета вещей устанавливает это значение в сообщениях, отправляемых с устройства в облако. Оно содержит идентификатор модели устройства, указанный в подключении устройства. | No | $dt-dataschema |
| dt-subject | Имя компонента, который отправляет сообщения с устройства в облако. | Да | $dt-subject |
Свойства приложения сообщений из устройства в облако
Обычно свойства приложения применяются для отправки метки времени с устройства с помощью свойства iothub-creation-time-utc для регистрации времени отправки сообщения устройством. Такая метка времени должна быть в формате UTC без сведений о часовом поясе. Например, значение 2021-04-21T11:30:16Z является допустимым, а 2021-04-21T11:30:16-07:00 — нет.
{
"applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
"messageSource":"telemetry",
"deviceId":"sample-device-01",
"schema":"default@v1",
"templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
"enqueuedTime":"2021-01-29T16:45:39.143Z",
"telemetry":{
"temperature":8.341033560421833
},
"messageProperties":{
"iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
},
"enrichments":{}
}
Системные свойства сообщений из облака на устройство
| Свойство | Description | Задается пользователем? |
|---|---|---|
| message-id | Задаваемый пользователем идентификатор сообщения, используемый для шаблонов типа "запрос-ответ". Формат: строка с учетом регистра (до 128 символов длиной) 7-разрядных буквенно-цифровых символов ASCII плюс - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Да |
| sequence-number | Число (уникальное для каждой очереди устройства), которое Центр Интернета вещей назначает каждому сообщению, отправленному из облака на устройство. | No |
| до | Место назначения, которое указывается в сообщениях, отправляемых из облака на устройство. | No |
| absolute-expiry-time | Дата и время истечения срока действия сообщения. | Да |
| correlation-id | Строковое свойство в сообщении ответа, которое обычно содержит идентификатор сообщения запроса в шаблонах "запрос-ответ". | Да |
| user-id | Идентификатор, используемый для указания источника сообщений. Когда сообщения создаются Центр Интернета вещей, идентификатор пользователя — это имя центра Интернета вещей. | Да |
| iothub-ack | Генератор отзывов на сообщения. Это свойство используется в сообщениях, отправляемых из облака в устройство, чтобы запросить у Центра Интернета вещей отправку отзыва после того, как сообщение будет использовано устройством. Возможные значения: none (по умолчанию) — отзывы не создаются, positive — отзыв будет получен, когда исходное сообщение будет передано, negative — отзыв будет получен, когда истечет срок действия исходного сообщения (или будет превышен лимит доставок) и при этом устройство его не примет, full — активированы значения positive и negative. | Да |
Имена системных свойств
Имена системных свойств различаются в зависимости от конечной точки, на которую отправляются сообщения.
| Имя системного свойства | Event Hubs | Хранилище Azure | Cлужебная шина | Сетка событий |
|---|---|---|---|---|
| Идентификатор сообщения | message-id | messageId | MessageId | message-id |
| Идентификатор пользователя | user-id | userId | UserId | user-id |
| Идентификатор устройства подключения | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Идентификатор модуля подключения | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| Идентификатор создания проверки подлинности подключения | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Метод проверки подлинности подключения | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | тип_содержимого | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | Н/П | iothub-enqueuedtime |
| CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Размер сообщения
Центр Интернета вещей измеряет размер сообщения вне зависимости от протокола, учитывая только фактический объем полезных данных. Размер в байтах вычисляется как сумма следующих значений:
- размер текста в байтах;
- размер в байтах всех значений свойств системы сообщений;
- размер в байтах всех имен и значений свойств пользователей.
Имена и значения свойств ограничены символами ASCII, то есть длина строк равна размеру в байтах.
Свойства для защиты от спуфинга
Чтобы избежать спуфинга устройств при работе с сообщениями, отправляемыми с устройства в облако, Центр Интернета вещей отмечает все сообщения такими свойствами:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
Первые два свойства содержат параметры deviceId и generationId исходного устройства согласно разделу о свойствах удостоверений устройств.
Свойство iothub-connection-auth-method содержит сериализованный объект JSON, имеющий следующие свойства.
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Следующие шаги
- Сведения об ограничениях на размер сообщений в Центре Интернета вещей см. в статье Руководство. Квоты и регулирование в Центре Интернета вещей.
- Узнайте, как создавать и читать сообщения Центра Интернета вещей на разных языках программирования, из этих кратких руководств.
- Сведения о структуре событий, не связанных с телеметрией, генерируемых Центром Интернета вещей, см. в разделе Схемы нетелеметрических событий Центра Интернета вещей.