Поделиться через

справочник по API уровня данных MQTT 5 (не рекомендуется) Центр Интернета вещей

  • Статья

В этом документе описаны операции, доступные в версии 2.0 (api-version: 2020-10-01-preview) API плоскости данных Центра Интернета вещей.

Примечание.

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

Операции

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

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

Запросить

Имя раздела: $iothub/twin/get

Свойства: нет

Полезные данные: пусто

Ответ при успешном выполнении

Свойства: нет

Полезные данные: Twin

Альтернативные ответы

Состояние Имя Описание
0100 ошибка запроса Сообщение операции неправильно обработано и не может быть обработано.
0101 Не авторизован Клиент не авторизован для выполнения операции.
0102 Запрещено Операция не разрешена.
0501 Регулируемый Слишком высокая частота запросов на номер SKU.
0502 Превышена квота Превышена дневная квота на текущий номер SKU.
0601 Ошибка сервера Внутренняя ошибка сервера.
0602 Время ожидания Время ожидания операции истекло до ее завершения.
0603 Сервер занят. Сервер занят.

Пример псевдокода


-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

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

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

Запросить

Имя раздела: $iothub/twin/patch/reported

Свойства.

Имя. Type Обязательно Описание
if-version u64 no

Полезные данные:: TwinState

Ответ при успешном выполнении

Свойства.

Имя. Type Обязательно Описание
версия u64 yes Версия сообщаемого состояния после применения исправления

Полезные данные: пусто

Альтернативные ответы

Состояние Имя Описание
0104 Необходимое условие не выполнено предварительные условия не были выполнены, что привело к отмене запроса
0100 ошибка запроса Сообщение операции неправильно обработано и не может быть обработано.
0101 Не авторизован Клиент не авторизован для выполнения операции.
0102 Запрещено Операция не разрешена.
0501 Регулируемый Слишком высокая частота запросов на номер SKU.
0502 Превышена квота Превышена дневная квота на текущий номер SKU.
0601 Ошибка сервера Внутренняя ошибка сервера.
0602 Время ожидания Время ожидания операции истекло до ее завершения.
0603 Сервер занят. Сервер занят.

Пример псевдокода


-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/reported
    [if-version: <u64>]
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Команды получения

Команды получения и обработки

Сообщение

Имя раздела: $iothub/commands

Свойства.

Имя. Type Обязательно Описание
sequence-no u64 yes Порядковый номер сообщения.
enqueued-time Время yes Метка времени, когда сообщение поступило в систему.
delivery-count u32 yes Количество попыток доставки сообщения.
creation-time Время no Метка времени создания сообщения (предоставляется отправителем).
message-id строка no Идентификатор сообщения (предоставляется отправителем).
user-id строка no Идентификатор пользователя (предоставляется отправителем).
correlation-id строка no Идентификатор корреляции (предоставляется отправителем).
Тип содержимого строка no Определяет тип содержимого полезных данных.
content-encoding строка no Определяет кодировку содержимого полезных данных.

Полезные данные: любая последовательность байтов.

Подтверждение успеха

Указывает, что команда была принята для обработки клиентом.

Свойства: нет

Полезные данные: пусто

Альтернативные подтверждения

Код основания Состояние Имя Описание
131 0603 Отказаться Указывает, что команда не будет обработана в настоящее время и должна быть повторно выполнена в будущем.
131 0100 Отклонить Указывает, что клиент отклонил команду, и она не должна быть предпринята повторно.

Пример псевдокода


-> SUBSCRIBE
    - Topic: $iothub/commands
      QoS: 1
<- PUBLISH
    QoS: 1
    Topic: $iothub/commands
    sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
    Payload: ...

-> PUBACK

Получение прямых методов

Получение и обработка вызовов прямых методов

Запросить

Имя раздела: $iothub/methods/{name}

Свойства: нет

Полезные данные: любая последовательность байтов.

Ответ при успешном выполнении

Свойства.

Имя. Type Обязательно Описание
response-code u32 yes

Полезные данные: любая последовательность байтов.

Альтернативные ответы

Состояние Имя Описание
06A0 Рекомендации недоступны Указывает, что клиент недоступен через это подключение.

Пример псевдокода


-> SUBSCRIBE
    - Topic: methods/{name}
      QoS: 0
<- SUBACK
<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/{name}
-> PUBLISH
    QoS: 0
    Topic: $iothub/responses

Получение изменений требуемого состояния двойника

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

Сообщение

Имя раздела: $iothub/twin/patch/desired

Свойства.

Имя. Type Обязательно Описание
версия u64 yes Версия требуемого состояния, соответствующая этому обновлению.

Полезные данные:: TwinState

Пример псевдокода


-> SUBSCRIBE
    - Topic: $iothub/twin/patch/desired
      QoS: 0
<- PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/desired
    version: <u64>
    Payload: ...

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

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

Сообщение

Имя раздела: $iothub/telemetry

Свойства.

Имя. Type Обязательно Описание
Тип содержимого строка no Преобразуется в системное свойство content-type в отправленном сообщении.
content-encoding строка no Преобразуется в системное свойство content-encoding в отправленном сообщении.
message-id строка no Преобразуется в системное свойство message-id в отправленном сообщении.
user-id строка no Преобразуется в системное свойство user-id в отправленном сообщении.
correlation-id строка no Преобразуется в системное свойство correlation-id в отправленном сообщении.
creation-time Время no Преобразуется в свойство iothub-creation-time-utc в отправленном сообщении.

Совет

Для creation-time нужно использовать формат UTC без сведений о часовом поясе. Например, 2021-04-21T11:30:16Z использовать можно, а 2021-04-21T11:30:16-07:00 — нет.

Полезные данные: любая последовательность байтов.

Подтверждение успеха

Сообщение успешно опубликовано в канал телеметрии.

Свойства: нет

Полезные данные: пусто

Альтернативные подтверждения

Код основания Состояние Имя Описание
131 0100 ошибка запроса Сообщение операции неправильно обработано и не может быть обработано.
135 0101 Не авторизован Клиент не авторизован для выполнения операции.
131 0102 Запрещено Операция не разрешена.
131 0601 Ошибка сервера Внутренняя ошибка сервера.
151 0501 Регулируемый Слишком высокая частота запросов на номер SKU.
151 0502 Превышена квота Превышена дневная квота на текущий номер SKU.
131 0602 Время ожидания Время ожидания операции истекло до ее завершения.
131 0603 Сервер занят. Сервер занят.

Пример псевдокода

-> PUBLISH
    QoS: 1
    Topic: $iothub/telemetry
    [Content Type: <string>]
    [content-encoding: <string>]
    [message-id: <string>]
    [user-id: <string>]
    [correlation-id: <string>]
    [creation-time: <time>]

<- PUBACK

Отклики

ошибка запроса

Сообщение операции неправильно обработано и не может быть обработано.

Код причины: 131

Состояние: 0100

Свойства.

Имя. Type Обязательно Описание
reason строка no содержит сведения о том, что конкретно не является допустимым для сообщения

Полезные данные: пусто

Конфликт

Операция конфликтует с другой текущей операцией.

Код причины: 131

Состояние: 0103

Свойства.

Имя. Type Обязательно Описание
trace-id строка no Идентификатор трассировки для корреляции с другими диагностика для ошибки
reason строка no содержит сведения о том, что конкретно не является допустимым для сообщения

Полезные данные: пусто

Запрещено

Операция не разрешена.

Код причины: 131

Состояние: 0102

Свойства.

Имя. Type Обязательно Описание
reason строка no содержит сведения о том, что конкретно не является допустимым для сообщения

Полезные данные: пусто

Не авторизован

Клиент не авторизован для выполнения операции.

Код причины: 135

Состояние: 0101

Свойства.

Имя. Type Обязательно Описание
trace-id строка no Идентификатор трассировки для корреляции с другими диагностика для ошибки

Полезные данные: пусто

Не найдено

запрошенный ресурс не существует

Код причины: 131

Состояние: 0504

Свойства.

Имя. Type Обязательно Описание
reason строка no содержит сведения о том, что конкретно не является допустимым для сообщения

Полезные данные: пусто

Не изменен

Ресурс не был изменен на основе предоставленных предварительных условий.

Код причины: 0

Состояние: 0001

Свойства: нет

Полезные данные: пусто

Необходимое условие не выполнено

Предварительные условия не были выполнены, что привело к отмене запроса

Код причины: 131

Состояние: 0104

Свойства: нет

Полезные данные: пусто

Превышена квота

Превышена дневная квота на текущий номер SKU.

Код причины: 151

Состояние: 0502

Свойства: нет

Полезные данные: пусто

Возможности ресурса исчерпаны

У ресурса нет возможностей для завершения операции.

Код причины: 131

Состояние: 0503

Свойства.

Имя. Type Обязательно Описание
reason строка no содержит сведения о том, что конкретно не является допустимым для сообщения

Полезные данные: пусто

Сервер занят.

Сервер занят.

Код причины: 131

Состояние: 0603

Свойства.

Имя. Type Обязательно Описание
trace-id строка no Идентификатор трассировки для корреляции с другими диагностика для ошибки

Полезные данные: пусто

Ошибка сервера

Внутренняя ошибка сервера.

Код причины: 131

Состояние: 0601

Свойства.

Имя. Type Обязательно Описание
trace-id строка no Идентификатор трассировки для корреляции с другими диагностика для ошибки

Полезные данные: пусто

Сбой целевого объекта

Целевой объект прислал ответ, но ответ был недопустимым или неправильно сформирован.

Код причины: 131

Состояние: 06A2

Свойства.

Имя. Type Обязательно Описание
reason строка no содержит сведения о том, что конкретно не является допустимым для сообщения

Полезные данные: пусто

Истекло время ожидания целевого объекта

Истекло время ожидания выполнения запроса целевым объектом.

Код причины: 131

Состояние: 06A1

Свойства.

Имя. Type Обязательно Описание
trace-id строка no Идентификатор трассировки для корреляции с другими диагностика для ошибки
reason строка no содержит сведения о том, что конкретно не является допустимым для сообщения

Полезные данные: пусто

Целевой объект недоступен

Целевой объект недоступен для выполнения запроса.

Код причины: 131

Состояние: 06A0

Свойства: нет

Полезные данные: пусто

Регулируемый

Слишком высокая частота запросов на номер SKU.

Код причины: 151

Состояние: 0501

Свойства: нет

Полезные данные: пусто

Время ожидания

Время ожидания операции истекло до ее завершения.

Код причины: 131

Состояние: 0602

Свойства.

Имя. Type Обязательно Описание
trace-id строка no Идентификатор трассировки для корреляции с другими диагностика для ошибки

Полезные данные: пусто