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

  • Статья

Центр Интернета вещей дает возможность вызова прямых методов на устройствах из облака. Прямые методы представляют собой взаимодействие типа "запрос — ответ" с устройством, подобное вызову HTTP тем, что об успешном завершении или сбое становится известно немедленно (после указанного пользователем времени ожидания). Этот подход полезен для сценариев, в которых предпринимаемые немедленно действия различаются в зависимости от того, удалось ли устройству ответить.

Примечание

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

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

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

Прямые методы следуют шаблону "запрос и ответ" и предназначены для взаимодействия, требующего немедленного подтверждения результата. Например, для интерактивного управления устройством (включение вентилятора).

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

Жизненный цикл метода

Прямые методы реализуются на устройстве. Чтобы процесс создания экземпляра прошел удачно, может потребоваться указать входные данные в полезных данных метода или не указывать их. Вызов прямого метода осуществляется через обращенный к службе URI ({iot hub}/twins/{device id}/methods/). Устройство получает прямые методы через раздел MQTT для устройства ($iothub/methods/POST/{method name}/) или ссылки AMQP (свойств приложения IoThub-methodname и IoThub-status).

Примечание

При вызове прямого метода на устройстве имена и значения свойств могут содержать только печатаемые буквенно-цифровые знаки US-ASCII, кроме любого из следующих: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}.

Прямые методы являются синхронными и либо завершаются успешно, либо не работают по истечении периода ожидания (по умолчанию: 30 секунд, настраивается от 5 до 300 секунд). Они полезны в интерактивных сценариях, когда нужно, чтобы устройство отвечало, только если оно находится в сети и принимает команды, такие как включение света с помощью телефона. В этих случаях об успешном или неудачном выполнении нужно узнавать немедленно, чтобы облачная служба смогла как можно быстрее отреагировать с учетом результата. В результате выполнения метода устройство может возвратить некоторый текст сообщения. Однако это действие не является обязательным для метода. Упорядочивание или обеспечение какой-либо семантики параллелизма при вызове метода не гарантировано.

Прямые методы — это только HTTPS со стороны облака и MQTT, AMQP, MQTT через WebSockets или AMQP через WebSockets со стороны устройства.

Полезными данными для запросов и ответов метода является документ JSON объемом не более 128 КБ.

Вызов прямого метода из серверного приложения

Чтобы вызвать прямой метод из серверного приложения, используйте REST API Вызов метода устройства или его эквивалент в одном из Пакетов SDK службы Центра Интернета вещей.

Вызов метода

Вызов прямого метода на устройстве является вызовом HTTPS, который состоит из следующих элементов:

  • URI перенаправления конкретного устройства вместе с версией API:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • метод POST;

  • Заголовки, содержащие сведения об авторизации, тип и кодировку содержимого.

  • прозрачный текст JSON в следующем формате:

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

Значение, указанное в запросе как responseTimeoutInSeconds — это время, в течение которого служба Центра Интернета вещей должна ожидать завершения выполнения прямого метода на устройстве. Установите этот тайм-аут как минимум равным ожидаемому времени выполнения устройством прямого метода. Если тайм-аут не указан, используется значение по умолчанию 30 секунд. Минимальные и максимальные значения для responseTimeoutInSeconds составляют 5 и 300 секунд соответственно.

Значение, указанное в запросе как connectTimeoutInSeconds, представляет собой количество времени после вызова прямого метода, в течение которого служба Центра Интернета вещей должна ожидать, чтобы отключенное устройство подключилось к сети. Значение по умолчанию — 0, что означает, что устройства уже должны быть подключены к сети после вызова прямого метода. Максимальное значение для connectTimeoutInSeconds — 300 секунд.

Пример

Этот пример позволит вам безопасно инициировать запрос на вызов прямого метода на устройстве Интернета вещей, зарегистрированном в Центре Интернета вещей Azure.

Для начала используйте расширение Интернета вещей Microsoft Azure для Azure CLI, чтобы создать SharedAccessSignature.

az iot hub generate-sas-token -n <iothubName> --du <duration>

Затем замените заголовок Authorization вновь созданным SharedAccessSignature, а затем измените параметры iothubName, deviceId, methodName и payload в соответствии с вашей реализацией в приведенном ниже примере команды curl.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

Выполните измененную команду, чтобы вызвать указанный прямой метод. Успешные запросы вернут код состояния HTTP 200.

Примечание

В приведенном выше примере демонстрируется вызов прямого метода на устройстве. Если требуется вызвать прямой метод в модуле IoT Edge, вам нужно будет изменить запрос URL-адреса, как показано ниже:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

Ответ

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

  • Код состояния HTTP:

    • 200 указывает на успешное выполнение прямого метода;
    • 404 указывает, что либо идентификатор устройства недействителен, либо устройство не было подключено к сети при вызове прямого метода и для connectTimeoutInSeconds после этого (используйте сопроводительное сообщение об ошибке, чтобы понять основную причину);
    • 504 указывает тайм-аут шлюза, вызванный тем, что устройство не отвечает на прямой вызов метода в responseTimeoutInSeconds.

  • Заголовки, содержащие идентификатор запроса, тип и кодировку содержимого.

  • текст JSON в следующем формате:

    {
    "status" : 201,
    "payload" : {...}
}

    Значения status и payload предоставляются устройством и используются для ответа, который содержит код состояния устройства и ответ метода.

Вызов метода для модулей IoT Edge

Вызов прямых методов модуля поддерживается REST API Вызов метода модуля или его эквивалентом в одном из пакетов SDK службы Центра Интернета вещей.

moduleId передается вместе с deviceId в URI запроса при использовании REST API или в качестве параметра при использовании пакета SDK службы. Например, https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Текст и ответ запроса аналогичны тексту и ответу прямых методов, вызываемых на устройстве.

Обработка прямого метода на устройстве

На устройстве Интернета вещей прямые методы могут быть получены через MQTT, AMQP или любой из этих протоколов через WebSockets. Пакеты SDK для устройств Центра Интернета вещей помогают получать и реагировать на прямые методы на устройствах, не беспокоясь о базовых сведениях протокола.

MQTT

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

Вызов метода

Устройства получают запросы на прямой метод в разделе MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Тем не менее, request id создается Центром Интернета вещей, это не может быть известно заранее, поэтому подпишитесь на $iothub/methods/POST/# и затем отфильтруйте доставленные сообщения на основе имен методов, поддерживаемых вашим устройством. (Вы будете использовать request id для ответа.)

Устройство получает текст следующего формата:

{
    "input1": "someInput",
    "input2": "anotherInput"
}

Запросы метода имеют нулевой уровень качества обслуживания.

Ответ

Устройство отправляет ответы в $iothub/methods/res/{status}/?$rid={request id}, где:

  • свойство status — это состояние выполнения метода, которое поддерживает устройство;

  • свойство $rid — это идентификатор запроса из вызова метода, полученного от Центра Интернета вещей. Идентификатор запроса является шестнадцатеричным форматированным значением.

Текст задает устройство. Он может находиться в любом состоянии.

AMQP

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

Вызов метода

Устройство получает запросы на прямые методы путем создания ссылки для адреса amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Сообщение AMQP приходит на ссылку приема, представляющую запрос метода. Он содержит следующие подразделы:

  • свойство идентификатора корреляции, содержащее идентификатор запроса, который нужно передать обратно с соответствующим ответом метода;

  • свойство приложения с именем IoThub-methodname, которое содержит имя вызываемого метода;

  • текст сообщения AMQP с полезными данными метода в формате JSON.

Ответ

Устройство создает ссылку на отправку для возврата ответа метода по адресу amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Ответ метода возвращается по отправляющей ссылке и имеет следующую структуру:

  • Свойство идентификатора корреляции, которое содержит идентификатор запроса, переданный в сообщении запроса метода.

  • свойство приложения с именем IoThub-status, которое содержит состояние метода, указанное пользователем;

  • содержание сообщения AMQP с ответом метода в формате JSON.

Дополнительные справочные материалы

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

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

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

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