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

  • Статья

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

Примечание.

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

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

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

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

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

Прямые методы реализуются на устройстве. Чтобы процесс создания экземпляра прошел удачно, может потребоваться указать входные данные в полезных данных метода или не указывать их. Вызов прямого метода осуществляется через обращенный к службе 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-адреса, чтобы включить /modules/<moduleName> его, как показано ниже:

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

Response

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

  • Код состояния 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"
}

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

Response

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

Response

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

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

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

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

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

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

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