Понять и вызвать прямые методы из IoT Hub

Использование прямых методов в IoT Hub позволяет удаленно вызывать команды на устройствах из облака. Прямые методы следуют шаблону ответа запроса и предназначены для обмена данными, которые требуют немедленного подтверждения их результата. Например, интерактивный контроль устройства, например включение вентилятора. Эта функция полезна для сценариев, когда ход немедленного действия отличается в зависимости от того, сможет ли устройство реагировать.

Примечание.

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

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

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

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

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

Прямые методы реализуются на устройстве и могут требовать никаких или одного и более входных данных в нагрузке метода для правильного инстанцирования. Вы вызываете прямой метод через 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 Devices - Invoke Method или его эквивалент в одном из пакетов SDK службы IoT Hub.

Вызов метода

Вызовы прямых методов на устройстве — это вызовы 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 IoT для Azure CLI, чтобы создать SharedAccessSignature.

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

Затем замените заголовок авторизации только что созданным 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-запрос, чтобы включить /modules/<moduleName>, как показано в следующем примере:

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 Modules - Invoke Method или его эквивалент в одном из SDK службы IoT Hub.

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"
}

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

Ответ

Устройство отправляет ответы на $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.

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

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

  • Last updated on