Центр Интернета вещей поддержка MQTT 5 (не рекомендуется)

Версия: 2.0 api-version: 2020-10-01-preview

В этом документе описан API плоскости данных Центра Интернета вещей по протоколу MQTT версии 5.0. Полные определения в этом API см. в справочнике по API.

Необходимые компоненты

• Создайте новый центр Интернета вещей с включенным режимом предварительной версии. MQTT 5 доступен только в режиме предварительной версии, и вы не можете переключить существующий центр Интернета вещей в режим предварительной версии. Дополнительные сведения см. в разделе "Включить режим предварительного просмотра"
• Предварительное знание спецификации MQTT 5.

Уровень поддержки и ограничения

Поддержка MQTT 5 в Центре Интернета вещей доступна в предварительной версии и ограничена следующим образом (с передачей клиенту через свойства CONNACK, если явно не указано иное).

• Пока нет официальной поддержки пакетов SDK для устройств Интернета вещей Azure.
• Идентификаторы подписок не поддерживаются.
• Подписки на общий ресурс не поддерживаются.
• RETAIN не поддерживается.
• Maximum QoS имеет значение 1.
• Maximum Packet Size — 256 KiB (действуют дополнительные ограничения на операцию).
• Назначенные идентификаторы клиентов не поддерживаются.
• Keep Alive имеет ограничение 19 min (максимальная задержка для проверки активности — 28.5 min).
• Topic Alias Maximum имеет значение 10.
• Response Information не поддерживается; CONNACK не возвращает свойство Response Information, даже если CONNECT содержит свойство Request Response Information.
• Receive Maximum (максимальное количество разрешенных неподтвержденных пакетов PUBLISH (в направлении клиент — сервер) с QoS: 1) — 16.
• У одного клиента может быть не больше 50 подписок. Если клиент достигает предела подписки, SUBACK возвращает 0x97 код причины (превышена квота) для подписок.

Жизненный цикл подключения

Connection

Чтобы подключить клиент к Центру Интернета вещей с помощью этого API, установите подключение для каждой спецификации MQTT 5. Клиент должен отправить пакет CONNECT в течение 30 секунд после успешного подтверждения TLS (или сервер закроет подключение). Пример пакета CONNECT

-> CONNECT
    Protocol_Version: 5
    Clean_Start: 0
    Client_Id: D1
    Authentication_Method: SAS
    Authentication_Data: {SAS bytes}
    api-version: 2020-10-10
    host: abc.azure-devices.net
    sas-at: 1600987795320
    sas-expiry: 1600987195320
    client-agent: artisan;Linux

• Свойство Authentication Method является обязательным и определяет используемый метод проверки подлинности. Дополнительные сведения о способе проверки подлинности см. в разделе Проверка подлинности.
• Обработка свойства Authentication Data зависит от Authentication Method. Если параметр Authentication Method имеет значение SAS, то параметр Authentication Data является обязательным и должен содержать допустимую сигнатуру. Дополнительные сведения о данных проверки подлинности см. в разделе Проверка подлинности.
• Свойство api-version является обязательным и должно быть установлено в значение версии API, указанное в заголовке этой спецификации, чтобы можно было применить эту спецификацию.
• Свойство host определяет имя узла клиента. Оно является обязательным, если только расширение SNI не было представлено в записи Client Hello во время подтверждения TLS.
• sas-at определяет время подключения.
• sas-expiry определяет время окончания срока действия предоставленного SAS.
• client-agent при необходимости сообщает сведения о клиенте, создающем подключение.

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

<- CONNACK
    Session_Present: 1
    Reason_Code: 0x00
    Session_Expiry_Interval: 0xFFFFFFFF # included only if CONNECT specified value less than 0xFFFFFFFF and more than 0x00
    Receive_Maximum: 16
    Maximum_QoS: 1
    Retain_Available: 0
    Maximum_Packet_Size: 262144
    Topic_Alias_Maximum: 10
    Subscription_Identifiers_Available: 0
    Shared_Subscriptions_Available: 0
    Server_Keep_Alive: 1140 # included only if client did not specify Keep Alive or if it specified a bigger value

Эти свойства пакета CONNACK соответствуют спецификации MQTT 5. Они отражая возможности Центра Интернета вещей.

Проверка подлинности

Свойство Authentication Method в клиенте CONNECT определяет тип проверки подлинности, используемый для этого подключения.

• SAS — подписанный URL-адрес предоставляется в свойстве CONNECT Authentication Data.
• X509 — клиент использует проверку подлинности на основе сертификата клиента.

Проверка подлинности завершается ошибкой, если способ проверки подлинности не совпадает со способом, настроенным для клиента в Центре Интернета вещей.

Проверка подлинности имени пользователя и пароля, используемая в предыдущих версиях API, не поддерживается.

SAS

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

Строка для подписи должна быть сформирована следующим образом.

{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n

• host name является производным от расширения SNI (представленного клиентом в записи Client Hello во время подтверждения TLS) или от пользовательского свойства host в пакете CONNECT.
• Client Id — это идентификатор клиента в пакете CONNECT.
• sas-policy — при наличии определяет политику доступа для Центра Интернета вещей, используемую для проверки подлинности. Кодируется как пользовательское свойство в пакете CONNECT. Необязательно. Это означает, что параметры проверки подлинности в реестре устройств используются вместо этого.
• sas-at — при наличии указывает время подключения (текущее время). Кодируется как пользовательское свойство типа time в пакете CONNECT.
• sas-expiry определяет срок действия проверки подлинности. Это пользовательское свойство типа time в пакете CONNECT. Это обязательное свойство.

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

HMAC-SHA256 используется для хэширования строки на основе одного из симметричных ключей устройства. Затем значение хэша задается в качестве значения свойства Authentication Data.

X509

Если свойство Authentication Method имеет значение X509, Центр Интернета вещей проверяет подлинность подключения на основе предоставленного сертификата клиента.

Повторная проверка подлинности

Если используется проверка подлинности на основе SAS, рекомендуется использовать кратковременные маркеры проверки подлинности. Чтобы проверять подлинность подключения и запретить отключение из-за окончания срока действия, клиент должен выполнить повторную проверку подлинности, отправив пакет AUTH с Reason Code: 0x19 (повторная проверка подлинности).

-> AUTH
    Reason_Code: 0x19
    Authentication_Method: SAS
    Authentication_Data: {SAS bytes}
    sas-at: {current time}
    sas-expiry: {SAS expiry time}

Правила:

• Authentication Method должно совпадать с именем, используемым для первоначальной проверки подлинности.
• Если подключение изначально прошло проверку подлинности с использованием SAS на основе политики общего доступа, то сигнатура, используемая при повторной проверке подлинности, должна основываться на той же политике.

Если повторная проверка подлинности завершается успешно, Центр Интернета вещей отправляет пакет AUTH с Reason Code: 0x00 (успешно). В противном случае Центр Интернета вещей отправляет пакет DISCONNECT с Reason Code: 0x87 (не авторизовано) и закрывает подключение.

Отключение

Сервер может отключить клиент по нескольким причинам, в том числе:

• неправильное поведение клиента в том, что невозможно реагировать на отрицательное подтверждение (или ответ) напрямую,
• Сервер не может поддерживать состояние подключения в актуальном состоянии,
• другой клиент подключается к тому же удостоверению.

Сервер может отключиться с любым кодом причины, определенным в спецификации MQTT 5.0. Важные замечания

• 135 (Не авторизовано) при сбое повторной проверки подлинности, срок действия текущего маркера SAS или изменение учетных данных устройства.
• 142 (Смена сеанса) — при открытии нового подключения с тем же идентификатором клиента.
• 159 (Превышена скорость подключения) при превышении скорости подключения для Центра Интернета вещей.
• 131 (Ошибка, связанная с реализацией) — любые пользовательские ошибки, определенные в этом API. status и reason свойства используются для передачи дополнительных сведений о причине отключения (дополнительные сведения см. в разделе "Ответ ").

Операции

Все функции в этом API выражаются как операции. Ниже приведен пример операции отправки телеметрии.

-> PUBLISH
    QoS: 1
    Packet_Id: 3
    Topic: $iothub/telemetry
    Payload: Hello

<- PUBACK
    Packet_Id: 3
    Reason_Code: 0

Полные спецификации операций в этом API см. в Центр Интернета вещей справочнике по API уровня данных MQTT 5.

Разделы сообщений и подписки

Разделы, используемые в сообщениях операций в этом API, начинаются с $iothub/. Семантика брокера MQTT не применяется к этим операциям (дополнительные сведения см. в статье Разделы, начинающиеся с $"). Разделы, начинающиеся с $iothub/ и не определенные в этом API, не поддерживаются.

• Отправка сообщений в неопределенный раздел приводит к Not Found ответу (см. ответ на подробные сведения)
• Подписка на неопределенный раздел приводит к SUBACK с кодом причины Reason Code: 0x8F (Недопустимый фильтр разделов).

Имена разделов и свойств чувствительны к регистру и должны точно совпадать. Например, $iothub/telemetry/ не поддерживается, а $iothub/telemetry поддерживается.

Типы взаимодействия

Все операции в этом API основаны на одном из двух типов взаимодействия.

• Сообщение с дополнительным подтверждением (MessageAck)
• Запрос и ответ (ReqRep)

Операции также зависят от направления (определяется направлением начального сообщения в операции обмена).

• Клиент — сервер (C2S)
• Сервер — клиент (S2C)

Например, отправка данных телеметрии является операцией "клиент — сервер" типа "сообщение с подтверждением", тогда как обработка прямого метода — это операция "сервер — клиент" типа "запрос и ответ".

Взаимодействия подтверждения сообщений

Сообщение с необязательным подтверждением (MessageAck) выражается как обмен пакетами PUBLISH и PUBACK в MQTT. Подтверждение является необязательным, и отправитель может не запрашивать его, отправляя PUBLISH пакет с QoS: 0помощью .

Пример простого взаимодействия MessageAck

Сообщение:

PUBLISH
    QoS: 1
    Packet_Id: 34
    Topic: $iothub/{request.path}
    Payload: <any>

Подтверждение (успешное выполнение):

PUBACK
    Packet_Id: 34
    Reason_Code: 0

Взаимодействия "запрос и ответ"

При взаимодействии "запрос и ответ" (ReqRep) как запрос, так и ответ переводятся в пакеты PUBLISH с QoS: 0.

Свойство Correlation Data должно быть задано в запросе и ответе для сопоставления пакета ответа с пакетом запроса.

Этот API использует один раздел ответа $iothub/responses для всех операций ReqRep. Подписка и отмена подписки на этот раздел для операций "клиент — сервер" не требуется — сервер предполагает, что все клиенты подписаны.

Пример простого взаимодействия ReqRep

Запрос:

PUBLISH
    QoS: 0
    Topic: $iothub/{request.path}
    Correlation_Data: 0x01 0xFA
    Payload: ...

Ответ (успешное выполнение):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: ...

Взаимодействия ReqRep не поддерживают пакеты PUBLISH с QoS: 1 в качестве сообщений запроса или ответа. Отправка результатов запроса PUBLISH в ответе Bad Request.

Максимальная поддерживаемая длина в свойстве Correlation Data — 16 байт. Если для свойства Correlation Data пакета PUBLISH задано значение более 16 байт, Центр Интернета вещей отправляет DISCONNECT с результатом Bad Request и закрывает соединение. Это поведение применяется только к пакетам, переданным через этот API.

Центр Интернета вещей автоматически подписывает клиентов на разделы ответов для всех операций "клиент — сервер". Даже если клиент явно отменяет подписку на раздел ответа, Центр Интернета вещей автоматически возобновляет ее. Для взаимодействий ReqRep типа "сервер — клиент" по-прежнему требуется, чтобы устройство имело подписку.

Свойства сообщения

Свойства операции — системные или пользовательские — указываются в виде свойств пакетов в MQTT 5.

В именах пользовательских свойств учитывается регистр, и их необходимо указывать в точности так, как они определены. Например, Trace-ID не поддерживается, а trace-id поддерживается.

Запросы с пользовательскими свойствами вне спецификации и без указания префикса @ приводят к ошибке.

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

Если разрешены определяемые пользователем свойства, их имена должны соответствовать формату @{property name}. Определяемые пользователем свойства поддерживают только допустимые строковые значения UTF-8. Например, свойство MyProperty1 со значением 15 должно быть закодировано как пользовательское свойство с именем @MyProperty и значением 15.

Если Центр Интернета вещей не распознает свойство User, оно считается ошибкой и Центр Интернета вещей отвечает с помощью Reason Code: 0x83 (ошибка, связанная с PUBACK реализацией) и status: 0100 (недопустимый запрос). Если подтверждение не было запрошено (QoS: 0), DISCONNECT пакет с той же ошибкой отправляется обратно и подключение завершается.

Этот API определяет следующие типы данных, помимо string.

• time: число миллисекунд с момента 1970-01-01T00:00:00.000Z. Например, 1600987195320 для 2020-09-24T22:39:55.320Z.
• u32: 32-разрядное целое число без знака.
• u64: 64-разрядное целое число без знака.
• i32: 32-разрядное целое число со знаком.

Response

Взаимодействие может привести к различным результатам: Success, Bad Request, Not Found и другим. Результаты различаются по пользовательском свойству status. Reason Code в пакетах PUBACK (для взаимодействий MessageAck) соответствует status, где это возможно.

Каждое взаимодействие имеет значение по умолчанию (то есть "успешно"). Оно имеет параметр Reason Code, равный 0, а свойство status не задано. В противном случае:

• Для взаимодействий MessageAck PUBACK возвращает Reason Code, кроме 0x0 (успешно). Свойство status может уточнять результат.
• Для взаимодействий ReqRep у ответа PUBLISH задается свойство status.
• Так как не существует способа реагирования на взаимодействия MessageAck с помощью QoS: 0 напрямую, отправляется пакет DISCONNECT со сведениями об ответе, а затем выполняется отключение.

Примеры:

Недопустимый запрос (MessageAck):

PUBACK
    Reason_Code: 131
    status: 0100
    reason: Unknown property `test`

Не авторизовано (MessageAck):

PUBACK
    Reason_Code: 135
    status: 0101

Не авторизовано (ReqRep):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: ...
    status: 0101

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

• status — расширенный код Центра Интернета вещей для состояния операции. Этот код можно использовать для различения результатов.
• trace-id— идентификатор трассировки для операции; Центр Интернета вещей может оставаться более диагностика в отношении операции, которая может использоваться для внутреннего расследования.
• reason — понятное сообщение, предоставляющее дополнительные сведения о том, почему операция завершилась с состоянием, указанным свойством status.

Код состояния

Свойство status содержит код состояния для операции. Он оптимизирован для эффективного чтения компьютером. Он состоит из 2-байтового целого числа без знака в шестнадцатеричном формате в строке, аналогичной 0501. Структура кода (битовая схема)

7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0
0 0 0 0 0 R T T | C C C C C C C C

Первый байт используется для флагов.

• биты 0 и 1 указывают тип результатов:
  • 00 — успешно
  • 01 — ошибка клиента
  • 10 — ошибка сервера
• Бит 2: 1 указывает, что ошибка позволяет выполнить повторную попытку.
• Биты 3–7 зарезервированы и должны иметь значение 0.

Второй байт содержит фактический уникальный код отклика. Коды ошибок с разными флагами могут иметь одинаковое значение второго байта. Например, могут существовать коды ошибок 0001, 0101, 0201, 0301 с разными значениями.

Например, Too Many Requests — это ошибка на стороне клиента, допускающая возможность повтора и имеющая код 1. Ее значение — 0000 0101 0000 0001 или 0x0501.

Клиенты могут использовать биты типа, чтобы определить, успешно ли завершилась операция. Клиенты также могут использовать бит возможности повторения, чтобы решить, разумно ли повторять операцию.

Рекомендации

Управление сеансом

Пакет CONNACK содержит свойство Session Present, указывающее, восстановил ли сервер ранее созданный сеанс. Используйте это свойство, чтобы выяснить, следует ли подписаться на разделы или пропустить подписку, так как она была выполнена ранее.

Для использования Session Present клиент должен следить за всеми созданными подписками (то есть когда он отправил пакет SUBSCRIBE и получил SUBACK с успешным кодом причины) или обязательно подписаться на все разделы в одном обмене SUBSCRIBE/SUBACK. В противном случае, если клиент отправляет два SUBSCRIBE пакета, а сервер обрабатывает только один из них успешно, сервер взаимодействует Session Present: 1 , CONNACK имея только часть подписок клиента.

Чтобы предотвратить ситуацию, когда более старая версия клиента не подписана на все разделы, лучше подписываться без соблюдения условий при изменении поведения клиента (например, в результате обновления встроенного ПО). Кроме того, чтобы гарантировать отсутствие устаревших подписок (поскольку их число ограничено), следует явно отменить подписки, которые больше не используются.

Пакетная обработка

Для отправки пакета сообщений не существует специального формата. Чтобы сократить издержки на ресурсоемкие операции в TLS и сети, объединяйте пакеты (PUBLISH, PUBACK, SUBSCRIBE и т. д.), прежде чем передать их в базовый стек TLS/TCP. Кроме того, клиент может упростить создание псевдонима раздела в группе пакетов.

• Укажите полное имя раздела в первом пакете PUBLISH для подключения и свяжите с ним псевдоним раздела.
• Добавьте следующие пакеты для того же раздела с пустым свойством имени и псевдонима раздела.

Миграция

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

• Транспортный протокол — MQTT 5. Ранее — MQTT 3.1.1.
• Контекстная информация для проверки подлинности SAS содержится в пакете CONNECT напрямую, а не кодируется вместе с сигнатурой.
• Указывается способ проверки подлинности.
• Подписанный URL-адрес помещается в свойство данных проверки подлинности. Раньше использовалось поле пароля.
• Разделы для операций отличаются:
  • Данные телеметрии: $iothub/telemetry вместо devices/{Client Id}/messages/events.
  • Команды: $iothub/commands вместо devices/{Client Id}/messages/devicebound.
  • Сообщение о двойнике исправления: $iothub/twin/patch/reported вместо $iothub/twin/PATCH/properties/reported.
  • Уведомление об изменении требуемого состояния двойника: $iothub/twin/patch/desired вместо $iothub/twin/PATCH/properties/desired.
• Подписка на раздел ответов операции "клиент — сервер" "запрос и ответ" не требуется.
• Пользовательские свойства используются вместо кодирования свойств в сегменте имени раздела.
• Имена свойств записываются в соответствии с соглашением об именовании через дефис, а не с помощью сокращений и специального префикса. Для определяемых пользователем свойств теперь требуется префикс. Например, $.mid теперь выглядит как message-id, а myProperty1 — как @myProperty1.
• Свойство данных корреляции используется для корреляции сообщений запроса и ответа в операциях типа "запрос — ответ" вместо свойства $rid, закодированного в разделе.
• Свойство iothub-connection-auth-method больше не отмечается для событий телеметрии.
• Команды C2D не очищаются при отсутствии подписки на устройстве. Они остаются в очереди до тех пор, пока устройство не подписывается или не истекает срок действия.

Примеры

Отправка данных телеметрии

Сообщение:

-> PUBLISH
    QoS: 1
    Packet_Id: 31
    Topic: $iothub/telemetry
    @myProperty1: My String Value # optional
    creation-time: 1600987195320 # optional
    @ No_Rules-ForUser-PROPERTIES: Any UTF-8 string value # optional
    Payload: <data>

Подтверждение.

<- PUBACK
    Packet_Id: 31
    Reason_Code: 0

Альтернативное подтверждение (регулируется):

<- PUBACK
    Packet_Id: 31
    Reason_Code: 151
    status: 0501

---

Отправить состояние получения двойника

Запрос:

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
    Correlation_Data: 0x01 0xFA
    Payload: <empty>

Ответ (успешное выполнение):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: <twin/desired state>

Ответ (не разрешено):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    status: 0102
    reason: Operation not allowed for `B2` SKU
    Payload: <empty>

---

Обработка вызовов прямых методов

Запрос:

<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/abc
    Correlation_Data: 0x0A 0x10
    Payload: <data>

Ответ (успешное выполнение):

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    response-code: 200 # user defined response code
    Payload: <data>

Ответ о недоступном устройстве:

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    status: 0603

---

Ошибка при использовании QoS 0, часть 1

Запрос:

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/gett # misspelled topic name - server won't recognize it as Request-Response interaction
    Correlation_Data: 0x0A 0x10
    Payload: <data>

Ответ:

<- DISCONNECT
    Reason_Code: 144
    reason: "Unsupported topic: `$iothub/twin/gett`"

---

Ошибка при использовании QoS 0, часть 2

Запрос:

-> PUBLISH # missing Correlation Data
    QoS: 0
    Topic: $iothub/twin/get
    Payload: <data>

Ответ:

<- DISCONNECT
    Reason_Code: 131
    status: 0100
    reason: "`Correlation Data` property is missing"

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

• Сведения о справочнике по API предварительной версии MQTT 5 см. в статье Центр Интернета вещей справочник по API MQTT 5 (предварительная версия).
• Чтобы изучить пример на C#, см. репозиторий примеров GitHub.