Обмен данными с Центром Интернета вещей с помощью протокола MQTT

В этой статье описывается, как устройства могут использовать протокол MQTT для взаимодействия с Центром Интернета вещей Azure. Конечные точки устройств Центра Интернета вещей поддерживают подключение устройств с помощью:

• MQTT версии 3.1.1 на порту 8883
• MQTT версии 3.1.1 через WebSocket на порту 443

Все коммуникации устройства с Центром Интернета вещей должны быть защищены с помощью TLS. Поэтому Центр Интернета вещей не поддерживает небезопасные подключения MQTT через порт 1883.

Сравнение поддержки MQTT в Центре Интернета вещей и сетке событий

Центр Интернета вещей не является полнофункциональным брокером MQTT и не поддерживает все функциональные возможности, указанные в стандарте MQTT версии 3.1.1. Если вашему решению требуется облачный брокер MQTT, используйте вместо этого сетку событий Azure . Event Grid обеспечивает двунаправленное взаимодействие между клиентами MQTT на гибких иерархических темах с помощью модели обмена сообщениями публикация-подписка. Кроме того, он позволяет направлять сообщения MQTT в другие службы Azure или пользовательские конечные точки для дальнейшей обработки.

В следующей таблице перечислены текущие различия в поддержке MQTT между двумя службами:

Подключение к Центру Интернета вещей

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

• Пакеты SDK для устройств Интернета вещей Azure.
• Протокол MQTT напрямую.

Многие корпоративные и образовательные брандмауэры блокируют порт MQTT (TCP-порт 8883). Если вы не можете открыть порт 8883 в брандмауэре, используйте MQTT через WebSockets. MQTT через WebSockets взаимодействует через порт 443, который почти всегда открыт. Сведения о том, как указать протоколы MQTT и MQTT через WebSockets при использовании SDK для Интернета вещей Azure, см. в статье "Использование SDK для устройств".

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

Пакеты SDK для устройств Интернета вещей Azure , поддерживающие протокол MQTT, доступны для Java, Node.js, C, C#и Python. Для установки подключения к Центру Интернета вещей пакеты SDK для устройств используют выбранный механизм проверки подлинности. Чтобы использовать протокол MQTT, параметр протокола клиента должен быть задан как MQTT. Можно также указать MQTT через WebSockets в параметре протокола клиента. По умолчанию пакеты SDK для устройств подключаются к Центру Интернета вещей, если для флага CleanSession установлено значение 0, и используют качество обслуживания первого уровня для обмена сообщениями с Центром Интернета вещей. Хотя можно настроить QoS 0 для ускорения обмена сообщениями, следует отметить, что доставка не гарантируется и не подтверждается. По этой причине QoS 0 часто называют «передай и забудь».

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

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

В следующем фрагменте показано, как указать протокол MQTT по протоколу WebSockets при использовании пакета SDK Node.js Azure IoT:

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

В следующем фрагменте показано, как указать протокол MQTT через WebSockets при использовании Python SDK для Azure IoT.

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

Таймаут поддержания активности по умолчанию

Чтобы поддерживать активное соединение клиента с концентратором Интернета вещей, сервис и клиент регулярно отправляют друг другу сигналы keep-alive. Если вы используете один из пакетов SDK устройства, клиент отправляет сообщение о сохранении активности через интервал, определенный в следующей таблице:

*Пакет SDK для C# определяет значение по умолчанию свойства MQTT KeepAliveInSeconds как 300 секунд. На самом деле, SDK отправляет запрос ping четыре раза за установленный период поддержания соединения. Другими словами, SDK отправляет сигнал поддержания соединения каждые 75 секунд.

В соответствии с спецификацией MQTT версии 3.1.1, интервал keep-alive IoT Hub составляет 1,5 раза больше, чем значение keep-alive клиента; однако IoT Hub ограничивает максимальное время ожидания на сервере до 29,45 минут (1767 секунд).

Например, устройство, использующее Java SDK отправляет запрос проверки на активность и теряет подключение к сети. Через 230 секунд устройство пропускает сигнал проверки подключения, так как оно находится в автономном режиме. Но Центр Интернета вещей не закрывает подключение немедленно — он ожидает еще (230 * 1.5) - 230 = 115 секунд, прежде чем отключить устройство с ошибкой 404104 DeviceConnectionClosedRemotely.

Максимальное время удержания соединения с клиентом, которое можно задать, — 1767 / 1.5 = 1177 секунд. Любой трафик сбрасывает сигнал поддержки соединения. Например, успешное обновление маркера общего доступа с использованием SAS обнуляет интервал поддержания активности.

Перенос приложения устройства из AMQP в MQTT

Если вы используете пакеты SDK для устройств, для перехода с использования AMQP на MQTT необходимо изменить параметр протокола в инициализации клиента.

При переходе с AMQP на MQTT проверьте следующие элементы:

• AMQP возвращает ошибки для многих условий, а MQTT завершает подключение. В результате может потребоваться изменить логику обработки исключений.

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

• AMQP не поддерживается в Python SDK.

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

Если устройство не может использовать пакеты SDK для устройств Интернета вещей, оно по-прежнему может подключаться к конечным точкам общедоступных устройств с помощью протокола MQTT через порт 8883.

В пакете CONNECT устройство должно использовать следующие значения.

• В поле Идентификатор клиента укажите значение идентификатор устройства.

• Для поля "Имя пользователя" используйте {iotHub-hostname}/{device-id}/?api-version=2021-04-12, где {iotHub-hostname} - это полное CName для хаба IoT.

  Например, если имя центра Интернета вещей contoso.azure-devices.net и если имя устройства — MyDevice01, поле имени пользователя содержит следующее:

  contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

  Чтобы избежать непредвиденного поведения, включите версию API в поле.

• В поле Пароль укажите маркер SAS. В следующем фрагменте кода показан формат маркера SAS:

  SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

  Примечание.

  Если вы используете аутентификацию с помощью сертификата X.509, пароли для маркеров SAS не требуются. Дополнительные сведения см. в руководстве по созданию и отправке сертификатов для тестирования и выполнения инструкций по коду в разделе конфигурации TLS.

  Дополнительные сведения о создании маркеров SAS см. в разделе «Использование маркеров SAS в качестве устройства» в «Управление доступом к IoT Hub с помощью подписей общего доступа».

  Вы также можете использовать расширение Центра Интернета вещей Azure для Visual Studio Code или команду расширения CLI az iot hub generate-sas-token для генерации токена SAS. Затем можно скопировать и вставить маркер SAS в собственный код для тестирования.

  Расширение создает маркер SAS со следующей структурой:

  HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

  Часть этого токена используется в поле Пароль для подключения с использованием MQTT.

  SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

Приложение устройства может указать сообщение Will в пакете CONNECT. Приложение устройства должно использовать devices/{device-id}/messages/events/ или devices/{device-id}/messages/events/{property-bag} в качестве имени топика Уилл для определения сообщений Уилл, которые должны быть пересланы как сообщения телеметрии. В этом случае, если сетевое соединение закрыто, но пакет DISCONNECT ранее не был получен с устройства, то Центр Интернета вещей отправляет сообщение Will, содержащееся в пакете CONNECT, в канал телеметрии. Канал телеметрии может быть либо конечной точкой События по умолчанию, либо настраиваемой конечной точкой, определяемой маршрутизацией Центра Интернета вещей. Сообщение имеет свойство iothub-MessageType со значением Will, назначенным ему.

Использование протокола MQTT непосредственно из модуля

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

• Задайте идентификатор клиента {device-id}/{module-id}.

• При проверке подлинности с помощью имени пользователя и пароля задайте для имени пользователя значение <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12. Если вы используете SAS, используйте маркер SAS, связанный с удостоверением модуля в качестве пароля.

• Используйте devices/{device-id}/modules/{module-id}/messages/events/ в качестве раздела для публикации телеметрии.

• Используйте devices/{device-id}/modules/{module-id}/messages/events/ в качестве темы Will.

• Используйте devices/{device-id}/modules/{module-id}/# в качестве темы для получения сообщений.

• Темы GET и PATCH аналогичны для модулей и устройств.

• Тема состояния двойника одинакова для модулей и устройств.

Дополнительные сведения об использовании MQTT с модулями см. в конечной точке MQTT узла IoT Edge.

Примеры использования MQTT без пакета SDK для устройств Интернета вещей Azure

Репозиторий примеров MQTT для Интернета вещей содержит примеры на C/C++, Python и CLI, показывающие, как отправлять сообщения телеметрии, получать сообщения из облака на устройство и использовать двойники устройств без использования пакетов SDK для устройств Azure.

Примеры C/C++ используют библиотеку Eclipse Mosquitto

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

Конфигурация протокола TLS

Чтобы использовать протокол MQTT напрямую, клиент должен подключиться через TLS 1.2. Все попытки пропустить этот шаг завершаются ошибкой подключения.

Чтобы установить подключение TLS, может потребоваться скачать и ссылаться на корневой сертификат DigiCert Global G2, который использует Azure. Дополнительные сведения об этом сертификате см. на веб-сайте компании Digicert.

В следующем примере показано, как реализовать эту конфигурацию с помощью версии Python библиотеки Paho MQTT.

Сначала установите библиотеку Paho из командной строки:

pip install paho-mqtt

Затем запустите клиент в сценарии Python. Замените эти заполнители в следующем фрагменте кода:

• <local path to digicert.cer> — это путь к локальному файлу, который содержит корневой сертификат DigiCert. Этот файл можно создать путем копирования сведений о сертификате из certs.c в пакете Центра Интернета вещей Azure для C. Укажите строки -----BEGIN CERTIFICATE----- и -----END CERTIFICATE-----, удалите метки " в начале и в конце каждой строки, а также удалите знаки \r\n в конце каждой строки.

• <device id from device registry> — идентификатор устройства, добавленного в Центр Интернета вещей.

• <generated SAS token> — маркер SAS для устройства, созданного как описано ранее в этой статье.

• <iot hub name> — имя Центра Интернета вещей.

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"


def on_connect(client, userdata, flags, rc):
    print("Device connected with result code: " + str(rc))


def on_disconnect(client, userdata, rc):
    print("Device disconnected with result code: " + str(rc))


def on_publish(client, userdata, mid):
    print("Device sent message")


client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()

Чтобы выполнить проверку подлинности с помощью сертификата устройства, обновите предыдущий фрагмент кода с изменениями, указанными в следующем фрагменте кода. Дополнительные сведения о подготовке к аутентификации на основе сертификатов приведены в разделе "Получение сертификата ЦС X.509" из "Аутентификация посредством сертификатов X.509".

# Create the client as before
# ...

# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=None)

# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)

# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)

Отправка сообщений устройства в облако

После подключения устройство может отправлять сообщения в Центр Интернета вещей, используя devices/{device-id}/messages/events/ или devices/{device-id}/messages/events/{property-bag} в качестве имени темы. Элемент {property-bag} позволяет устройству отправлять сообщения с другими свойствами в формате, закодированном url-адресом. Рассмотрим пример.

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

В этом элементе {property_bag} используется та же кодировка символов, что и для строк запросов в протоколе HTTPS.

Если вы направляете сообщения D2C в учетную запись хранения Azure и хотите использовать кодировку JSON, необходимо указать сведения о типе контента и кодировке контента, включая $.ct=application%2Fjson&$.ce=utf-8, как часть {property_bag}, упомянутого выше комментария.

В следующем списке приведены особенности поведения, специфичные для реализации MQTT в IoT Hub.

• Центр Интернета вещей не поддерживает сообщения со вторым уровнем качества обслуживания. Если приложение устройства публикует сообщение с QoS 2, Центр Интернета вещей закрывает сетевое подключение.

• Центр Интернета вещей не сохраняет Retain сообщения. Если устройство отправляет сообщение с установленным значением флага RETAIN на 1, IoT Hub добавляет в сообщение приложенческое свойство mqtt-retain. В этом случае вместо сохранения сохраненного сообщения Центр Интернета вещей передает его в серверное приложение.

• Центр Интернета вещей поддерживает только одно активное подключение MQTT на устройство. Любое новое подключение MQTT от имени того же идентификатора устройства приводит к удалению существующего подключения и записи 400027 ConnectionForcefullyClosedOnNewConnection в журналы Центра Интернета вещей.

• Чтобы маршрутизировать сообщения на основе текста сообщения, сначала добавьте свойство ct в конец раздела MQTT и задайте его значение application/json;charset=utf-8 , как показано в следующем примере. Дополнительные сведения о маршрутизации сообщений на основе свойств или содержимого сообщения см. в документации по синтаксису запросов маршрутизации сообщений IoT Hub.

  devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

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

Получение сообщений из облака на устройство

Чтобы получать сообщения от IoT Hub, устройство должно подписаться, используя devices/{device-id}/messages/devicebound/# как Фильтр Темы. Многоуровневый подстановочный знак # в фильтре раздела позволяет устройству получать дополнительные свойства в имени раздела. Центр Интернета вещей не позволяет использовать подстановочные знаки # или ? для фильтрации подтем. Центр Интернета вещей не является брокером обмена сообщениями для публикации и подписки общего назначения, он поддерживает только задокументированные имена разделов и фильтры разделов. Устройство может подписываться только на пять разделов одновременно.

Устройство не получает сообщения из Центра Интернета вещей, пока не подпишется на конечную точку для конкретного устройства, представленную фильтром темы devices/{device-id}/messages/devicebound/#. После установки подписки устройство получает сообщения из облака на устройство, отправляемые в него после окончания срока действия подписки. Если устройство подключается с флагом CleanSession, имеющим значение 0, то подписка будет сохраняться в разных сеансах. В этом случае при следующем подключении устройства с CleanSession 0 оно получает все ожидающие сообщения, отправленные ему во время отсутствия подключения. Если устройство использует флаг CleanSession с значением 1, оно не получает сообщения от IoT Hub, пока не подпишется на конечную точку устройства.

Центр Интернета вещей передает сообщения с именем разделаdevices/{device-id}/messages/devicebound/ или devices/{device-id}/messages/devicebound/{property-bag} при наличии свойств сообщения. {property-bag} содержит закодированные в формате URL пары «ключ-значение» свойств сообщения. В контейнер свойств входят только свойства приложений и задаваемые пользователем системные свойства (такие как messageId или correlationId). Имена системных свойств имеют префикс $, свойства приложений используют исходное имя свойства без префикса. Дополнительные сведения о формате контейнера свойств см. в разделе "Отправка сообщений устройства в облако".

В сообщениях из устройства в облако значения в пакете свойств представлены в следующей таблице:

Следующие примеры демонстрируют пакет свойств, который содержит три свойства приложения: свойство1 со значением null; свойство2, пустая строка (""); и свойство3 со значением "строка".

/?prop1&prop2=&prop3=a%20string

Когда приложение устройства подписывается на раздел с QoS 2, Центр Интернета вещей предоставляет максимальный уровень качества обслуживания 1 в пакете SUBACK . После этого Центр Интернета вещей доставляет сообщения на устройство, используя первый уровень качества обслуживания.

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

Сначала устройство подписывается на $iothub/twin/res/#, чтобы получать ответы операции. Затем оно отправляет пустое сообщение в раздел $iothub/twin/GET/?$rid={request id} с заполненным значением request ID (идентификатор запроса). Затем служба отправляет ответное сообщение, содержащее данные двойника устройства в разделе $iothub/twin/res/{status}/?$rid={request-id}, используя то же значение идентификатора запроса, что и в запросе.

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

Тело ответа содержит раздел свойств двойника устройства, как показано в следующем примере ответа:

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

Возможны следующие коды состояний:

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

Обновить сообщенные свойства двойника устройства

Чтобы обновить сообщаемые свойства, устройство выдает запрос в Центр Интернета вещей путем публикации в указанном разделе MQTT. После обработки запроса Центр Интернета вещей отвечает на состояние успешной или неудачной операции обновления путем публикации в другом разделе. Устройство может подписаться на эту тему, чтобы получать уведомления о результате запроса на обновление двойника. Для реализации такого типа взаимодействия запроса и ответа в MQTT устройство предоставляет идентификатор запроса ($rid) в исходном запросе на обновление. Затем этот идентификатор запроса включается в ответ центра Интернета вещей, чтобы позволить устройству сопоставить ответ с правильным запросом.

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

1. Устройство сначала подписывается на $iothub/twin/res/# раздел, чтобы он мог получать ответы от Центра Интернета вещей.

2. Устройство отправляет сообщение, содержащее обновление двойника устройства, в тему $iothub/twin/PATCH/properties/reported/?$rid={request-id}. Это сообщение содержит значение request ID (идентификатор запроса).

3. Затем служба отправляет ответное сообщение, содержащее новое значение ETag для коллекции сообщаемых свойств в разделе $iothub/twin/res/{status}/?$rid={request-id}. В этом ответном сообщении используется то же значение request ID, что и в запросе.

Текст запроса содержит документ JSON, в котором имеются новые значения для переданных свойств. Каждый элемент документа JSON обновляет или добавляет соответствующий компонент в документе двойника устройства. Элемент, установленный на null, удаляет элемент из содержащего объекта. Рассмотрим пример.

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

Возможны следующие коды состояний:

Следующий фрагмент кода Python демонстрирует процесс обновления сообщенных свойств двойника через MQTT с помощью клиента Paho MQTT.

from paho.mqtt import client as mqtt

# authenticate the client with IoT Hub (not shown here)

client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
               rid, twin_reported_property_patch, qos=0)

Когда процесс обновления свойств двойника завершается успешно, Центр Интернета вещей публикует сообщение в следующем разделе: $iothub/twin/res/204/?$rid=1&$version=6где 204 код состояния, указывающий на успешность, соответствует идентификатору запроса, $rid=1 предоставленному устройством в коде, и $version соответствует версии раздела сообщаемых свойств двойников устройств после обновления.

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

Получение уведомлений об обновлении нужных свойств

При подключении устройства Центр Интернета вещей отправляет уведомления в раздел $iothub/twin/PATCH/properties/desired/?$version={new-version}, в котором находится содержимое обновления, выполненного серверной частью решения. Рассмотрим пример.

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

В обновлениях свойств значение null означает, что элемент объекта JSON удаляется. Кроме того, $version указывает новую версию раздела с требуемыми свойствами двойника.

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

Ответ на прямой метод

Сначала устройство подписывается на $iothub/methods/POST/#. IoT Hub отправляет запросы методов к теме $iothub/methods/POST/{method-name}/?$rid={request-id}, с либо допустимым JSON, либо пустым телом.

В качестве ответа устройство отправляет сообщение без текста или с допустимой строкой JSON в раздел $iothub/methods/res/{status}/?$rid={request-id}. В этом сообщении значение request ID должно совпадать с идентификатором в сообщении запроса, а в качестве status должно быть указано целое число.

Дополнительные сведения см. в статье Общие сведения о прямых методах и информация о вызове этих методов из Центра Интернета вещей.

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

Дополнительные сведения об использовании MQTT см. в следующей статье:

• Документация по MQTT
• Руководство. Использование MQTT для разработки клиента устройства Интернета вещей без использования пакета SDK для устройств
• Примеры приложений MQTT
• Azure IoT SDKs (Пакеты SDK для платформы Azure IoT)