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

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

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

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

Примечание

Некоторые функции, упоминаемые в этой статье, например обмен сообщениями между облаком и устройством, двойники устройств и управление устройствами, доступны только для Центра Интернета вещей уровня "Стандартный". Дополнительные сведения о базовых и стандартных и бесплатных уровнях Центр Интернета вещей см. в статье Выбор подходящего уровня Центр Интернета вещей для решения.

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

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

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

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

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

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

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

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

Язык Параметр протокола MQTT Параметр протокола MQTT через WebSockets
Node.js azure-iot-device-mqtt.Mqtt azure-iot-device-mqtt.MqttWs
Java IotHubClientProtocol.MQTT IotHubClientProtocol.MQTT_WS
C MQTT_Protocol MQTT_WebSocket_Protocol
C# TransportType.Mqtt TransportType.Mqtt возвращается к MQTT через WebSocket в случае сбоя MQTT. Чтобы указать MQTT только для WebSocket, используйте TransportType.Mqtt_WebSocket_Only
Python Поддерживает MQTT по умолчанию Добавьте websockets=True в вызов, чтобы создать клиент.

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

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

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

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

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

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

Язык Интервал проверки активности по умолчанию Настраивается
Node.js 180 секунд нет
Java 230 секунд Да
C 240 секунд Да
C# 300 секунд* Да
Python 60 секунд Да

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

В соответствии со спецификацией MQTT версии 3.1.1 интервал проверки связи Центр Интернета вещей в 1,5 раза больше, чем значение проверки активности клиента. Однако Центр Интернета вещей ограничивает максимальное время ожидания на стороне сервера 29,45 минуты (1767 секунд). Это ограничение существует, так как все службы Azure привязаны к времени ожидания простоя TCP подсистемы балансировки нагрузки Azure, которое составляет 29,45 минуты.

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

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

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

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

При этом обязательно проверьте следующее:

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

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

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

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

В репозитории примеров IoT MQTT вы найдете несколько демонстрационных проектов C/C++, в которых показано, как отправлять сообщения телеметрии и получать события с помощью Центра Интернета вещей без использования пакета SDK azure IoT для C.

В этих примерах используется библиотека Eclipse Mosquitto для отправки сообщений брокеру MQTT, реализованного в Центре Интернета вещей.

Дополнительные сведения об адаптации образцов для использования конвенций Azure IoT Plug and Play см. в Учебные материалы: использование MQTT для разработки IoT Plug and Play для устройства клиента.

Этот репозиторий содержит следующие примеры:

Для Windows.

  • mosquitto_telemetry содержит код для отправки сообщения телеметрии в Центр Интернета вещей Azure, созданного и выполняемого на компьютере с Windows.

  • mosquitto_subscribe содержит код для подписки на события данного Центра Интернета вещей на компьютере Windows.

  • mosquitto_device_twin содержит код для запроса событий двойника устройства в Центре Интернета вещей Azure на компьютере с Windows и подписки на него.

Для Linux.

  • MQTTLinux содержит код и скрипт сборки для запуска в Linux (WSL, Ubuntu и Raspbian были протестированы до сих пор).

  • LinuxConsoleVS2019содержит тот же код, но в проекте Visual Studio 2019 (VS2019), предназначенном для подсистема Windows для Linux (WSL). В этом проекте можно пошагово отлаживать выполняемый в Linux код в Visual Studio.

Для mosquitto_pub.

Эта папка содержит два примера команд, используемых с служебным средством mosquitto_pub, предоставляемым Eclipse Mosquitto.

  • При отправке сообщения текстовое сообщение отправляется в Центр Интернета вещей, выступающий в качестве устройства.

  • Подписка на события подписывается на события и отображает события, происходящие в Центре Интернета вещей.

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

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

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

  • В поле Username (Имя пользователя) укажите значение {iotHub-hostname}/{device-id}/?api-version=2021-04-12, где {iotHub-hostname} — это полная запись CName Центра Интернета вещей.

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

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

    Рекомендуем в поле указать api-версию. В противном случае может иметь место непредусмотренное поведение.

  • В поле Пароль укажите маркер SAS. Формат маркера SAS аналогичен описанному для протоколов HTTPS и AMQP:

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

    Примечание

    При использовании аутентификации с помощью сертификата X.509 пароли маркеров SAS не требуются. Дополнительные сведения см. в статье Настройка безопасности X.509 в вашем Центре Интернета вещей Azure и соблюдайте инструкции по коду в разделе настройки параметров TLS/SSL.

    Дополнительные сведения о создании маркеров SAS см. в разделе Использование маркеров SAS в качестве устройствастатьи Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов.

    Вы также можете использовать кроссплатформенный Azure IoT Tools для Visual Studio Code или команду расширения CLI az iot hub generate-sas-token, чтобы быстро создать маркер SAS. Затем вы можете скопировать и вставить маркер SAS в собственный код для тестирования.

Инструкции для Azure IoT Tools

  1. Разверните вкладку AZURE IOT HUB DEVICES (Устройства Центра Интернета вещей Azure) в левом нижнем углу Visual Studio Code.

  2. Щелкните устройство правой кнопкой мыши и выберите Generate SAS Token for Device (Создать маркер безопасности SAS для этого устройства).

  3. Задайте время истечения срока действия и нажмите клавишу "ВВОД".

  4. Маркер 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} в качестве значения параметра Will topic name (Будущее имя раздела) для определения будущих сообщений, которые будут пересылаться в качестве сообщения телеметрии. В этом случае, если сетевое соединение закрыто, но пакет DISCONNECT ранее не был получен с устройства, то Центр Интернета вещей отправляет сообщение Will, содержащееся в пакете CONNECT, в канал телеметрии. Канал телеметрии может быть либо конечной точкой События по умолчанию, либо настраиваемой конечной точкой, определяемой маршрутизацией Центра Интернета вещей. Сообщение имеет свойство iothub-MessageType со значением Will, назначенным ему.

Непосредственное использование протокола MQTT (как модуль)

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

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

  • При аутентификации с использованием имени пользователя и пароля задайте для имени пользователя значение <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 и используйте в качестве пароля маркер 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 с модулями см. в статье Публикация сообщений и создание подписки на них с помощью IoT Edge и дополнительные сведения о конечной точке MQTT центра IoT Edge.

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

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

Чтобы установить соединение TLS, может потребоваться скачать корневой сертификат DigiCert Baltimore и добавить ссылку на него. Этот сертификат используется в Azure для обеспечения безопасного подключения. Он хранится в репозитории Azure-iot-sdk-c. Дополнительные сведения об этих сертификатах можно найти на веб-сайте Digicert.

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

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

pip install paho-mqtt

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

  • <local path to digicert.cer> — путь к локальному файлу, содержащему корневой сертификат DigiCert Baltimore. Этот файл можно создать путем копирования сведений о сертификате из 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} примечания.

Формат этих атрибутов зависит от протокола. Центр Интернета вещей преобразует эти атрибуты в соответствующие системные свойства. Дополнительные сведения см. в разделе Свойства системыЦентр Интернета вещей синтаксисе запросов маршрутизации сообщений.

В следующем списке описано Центр Интернета вещей поведения, зависят от реализации.

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

  • Центр Интернета вещей не сохраняет сообщения retain. Если устройство направляет сообщение СОХРАНИТЬ с флажком установленном на 1, Центр Интернета вещей добавляет в сообщение свойство mqtt-retain приложения. В этом случае Центр Интернета вещей не хранит сообщение retain, а передает его во внутреннее приложение.

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

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

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

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

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

Для получения сообщений из Центра Интернета вещей устройство должно подписаться с использованием devices/{device-id}/messages/devicebound/# в качестве значения параметра Topic Filter (Фильтр разделов). Многоуровневый подстановочный знак # в фильтре тем используется только для того, чтобы разрешить устройству получать дополнительные свойства в имени раздела. В Центре Интернета вещей запрещено использовать подстановочные знаки # или ? для фильтрации подразделов. Так как Центр Интернета вещей не является брокером общего назначения службы сообщений на основе шаблона "издатель-подписчик", то он поддерживает только задокументированные имена и фильтры разделов.

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

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

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

Значение свойства Представление Описание
null key В пакете свойств отображается только ключ
пустая строка key= За ключом указывается знак "равно" без значения
не нулевое, не пустое значение key=value За ключом указывается знак "равно" и значение

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

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

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

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

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

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

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

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

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

Состояние Описание
200 Успешно
429 Слишком много запросов (регулируется). Дополнительные сведения см. в разделе регулирование Центр Интернета вещей.
5** ошибки сервера;

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

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

Чтобы обновить сообщаемые свойства, устройство отправляет запрос в Центр Интернета вещей с помощью публикации в указанном разделе 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
}

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

Состояние Описание
204 Успех (содержимое не возвращается)
400 Недопустимый запрос. Неправильно сформированный JSON.
429 Слишком много запросов (регулирование), как указано в статье Квоты и регулирование в Центре Интернета вещей
5** ошибки сервера;

В следующем фрагменте кода 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/#. Центр Интернета вещей отправляет запросы метода в раздел $iothub/methods/POST/{method-name}/?$rid={request-id} с допустимым документом JSON или без текста.

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

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

Дальнейшие действия

Дополнительные сведения о протоколе MQTT см. в документации по MQTT.

Дополнительные сведения о планировании развертывания Центра Интернета вещей см. в следующих руководствах:

Для дальнейшего изучения возможностей Центра Интернета вещей см. следующие статьи: