Создание и чтение сообщений Центра Интернета вещей
Чтобы обеспечить эффективное взаимодействие по протоколам, Центр Интернета вещей задает общий набор функций обмена сообщениями, доступный во всех протоколах для устройств. Их можно использовать как в маршрутизации сообщений с устройства в облако, так и в сообщениях из облака на устройство.
Примечание.
Некоторые функции, упоминаемые в этой статье, например обмен сообщениями между облаком и устройством, двойники устройств и управление устройствами, доступны только для Центра Интернета вещей уровня "Стандартный". Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.
Для реализация отправки сообщений с устройства в облако Центр Интернета вещей использует модель потоковой передачи сообщений. Сообщения Центра Интернета вещей, отправляемые с устройства в облако, больше похожи на событияЦентров событий, чем на сообщенияслужебной шины, где большое количество событий проходит через службу и может считываться несколькими модулями чтения.
Сообщение Центра Интернета вещей состоит из следующих компонентов.
Предварительно определенный набор системных свойств, которые приведены ниже.
Набор свойств приложения. Словарь свойств строки, которые приложение может задать и использовать без необходимости десериализации текста сообщения. Центр Интернета вещей никогда не изменяет эти свойства.
Текст сообщения, который может быть любым типом данных.
Каждый протокол устройства реализует свойства параметров различными способами. Дополнительные сведения см. в связанных руководствах разработчиков MQTT и AMQP.
При отправке сообщений с устройства в облако с помощью протокола HTTPS или отправке сообщений из облака на устройство имена и значения свойств могут содержать только буквенно-цифровые знаки ASCII и знаки {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'}.
Отправка сообщений с устройства в облако с помощью Центра Интернета вещей имеет следующие характеристики:
Сообщения, отправляемые с устройства в облако, устойчивы и хранятся в конечной точке по умолчанию messages/events Центра Интернета вещей до семи дней.
Размер сообщений, поступающих с устройства в облако, не может превышать 256 КБ, и их можно объединять в пакеты, чтобы оптимизировать отправку. Размер пакетов не может превышать 256 КБ.
Центр Интернета вещей не позволяет выполнять произвольное секционирование. Сообщения, отправляемые с устройства в облако, секционируются по исходному идентификатору deviceId.
Как поясняется в статье Управление доступом к Центру Интернета вещей, Центр Интернета вещей обеспечивает аутентификацию и контроль доступа для каждого устройства.
Можно пометить сообщения данными, которые будут передаваться в свойства приложения. Дополнительные сведения см. в разделе, посвященном обогащению сообщений.
Дополнительные сведения о способах кодировки и декодирования сообщений, отправляемых с помощью разных протоколов, см. в статье Понимание и использование пакетов SDK для Центра Интернета вещей Azure.
Примечание.
Каждый протокол Центра Интернета вещей предоставляет свойство типа контента сообщения, которое учитывается при маршрутизации данных в пользовательские конечные точки. Чтобы данные правильно обрабатывались в назначении (например, JSON обрабатывался как строка с возможностью синтаксического анализа вместо двоичных данных в кодировке Base64), необходимо указать соответствующий тип контента и кодировку для сообщения.
Чтобы использовать текст сообщения в запросе маршрутизации Центра Интернета вещей, необходимо указать допустимый объект JSON для сообщения и задать для свойства типа контента сообщения значение application/json;charset=utf-8.
Допустимый, маршрутизируемый текст сообщения может выглядеть следующим образом:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Системные свойства сообщений Центра Интернета вещей D2C
| Свойство | Description | Задается пользователем? | Ключевое слово для запроса маршрутизации |
|---|---|---|---|
| message-id | Задаваемый пользователем идентификатор сообщения, используемый для шаблонов типа "запрос-ответ". Формат: строка с учетом регистра (длиной до 128 знаков), состоящая из букв и цифр в 7-битовом формате ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Да | messageId |
| iothub-enqueuedtime | Дата и время получения сообщения, отправленного с устройства в облако, Центром Интернета вещей. | No | enqueuedTime |
| user-id | Идентификатор, используемый для указания источника сообщений. Если сообщения создает центр Интернета вещей, для этого параметра задается значение {iot hub name}. |
Да | 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 |
Свойства сообщений Центра Интернета вещей D2C
Обычно свойства приложения применяются для отправки метки времени с устройства с помощью свойства iothub-creation-time-utc для регистрации времени отправки сообщения устройством. Такая метка времени должна быть в формате UTC без сведений о часовом поясе. Например, метку 2021-04-21T11:30:16Z использовать можно, а метку 2021-04-21T11:30:16-07:00 — нет.
{
"applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
"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":{}
}
Системные свойства сообщений Центра Интернета вещей C2D
| Свойство | Description | Задается пользователем? |
|---|---|---|
| message-id | Задаваемый пользователем идентификатор сообщения, используемый для шаблонов типа "запрос-ответ". Формат: строка с учетом регистра (длиной до 128 знаков), состоящая из букв и цифр в 7-битовом формате ASCII + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Да |
| sequence-number | Число (уникальное для каждой очереди устройства), которое Центр Интернета вещей назначает каждому сообщению, отправленному из облака на устройство. | No |
| до | Место назначения, которое указывается в сообщениях, отправляемых из облака на устройство. | No |
| absolute-expiry-time | Дата и время истечения срока действия сообщения. | Да |
| correlation-id | Строковое свойство в сообщении ответа, которое обычно содержит идентификатор сообщения запроса в шаблонах "запрос-ответ". | Да |
| user-id | Идентификатор, используемый для указания источника сообщений. Если сообщения создает центр Интернета вещей, для этого параметра задается значение {iot hub name}. |
Да |
| 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"
}
Следующие шаги
- Сведения об ограничениях на размер сообщений в Центре Интернета вещей см. в статье Руководство. Квоты и регулирование в Центре Интернета вещей.
- Узнайте, как создавать и читать сообщения Центра Интернета вещей на разных языках программирования, из этих кратких руководств.
- Сведения о структуре событий, не связанных с телеметрией, генерируемых Центром Интернета вещей, см. в разделе Схемы нетелеметрических событий Центра Интернета вещей.