Understand and invoke direct methods from IoT Hub

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

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

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

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

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

Direct methods are implemented on the device and might require zero or more inputs in the method payload to correctly instantiate. Вы вызываете прямой метод через URI для взаимодействия с сервисом ({iot hub}/twins/{device id}/methods/). Устройство получает прямые методы через раздел MQTT для конкретного устройства ($iothub/methods/POST/{method name}/) или через ссылки AMQP (свойства приложения IoThub-methodname и IoThub-status).

Direct methods are synchronous and either succeed or fail after the time-out period (default 30 seconds; settable between 5 and 300 seconds). Прямые методы полезны в интерактивных сценариях, где требуется, чтобы устройство действовало, только если устройство находится в сети и получает команды. Например, включите свет с телефона. В этих сценариях вы хотите увидеть немедленный успех или сбой, чтобы облачная служба действовала на основании результата как можно скорее. Устройство может возвращать текст сообщения в результате метода, но это не обязательно. There's no guarantee on ordering or any concurrency semantics on method calls.

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

The payload for method requests and responses is a JSON document up to 128 KB.

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

To invoke a direct method from a back-end app, use the Devices - Invoke Method REST API or its equivalent in one of the IoT Hub service SDKs.

Method invocation

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

• The request URI specific to the device along with the API version:

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

• The POST method

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

• A transparent JSON body in the following format:

  {
      "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.

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

Ответ

Серверное приложение получает ответ, состоящий из следующих элементов:

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

  • 200 указывает на успешное выполнение прямого метода;
  • 404 indicates that either device ID is invalid, or that the device wasn't online upon invocation of a direct method and for connectTimeoutInSeconds thereafter (use accompanied error message to understand the root cause);
  • Код 504 указывает на истечение времени ожидания шлюза из-за того, что устройство не отвечает на прямой вызов метода в responseTimeoutInSeconds.

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

• A JSON body in the following format:

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

  Both status and payload are provided by the device and used to respond with the device's own status code and the method response.

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

To invoke a direct method on a module, use the Modules - Invoke Method REST API or its equivalent in one of the IoT Hub service SDKs.

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

Handle a direct method on a device

On an IoT device, direct methods can be received over MQTT, AMQP, or either of these protocols over WebSockets. The IoT Hub device SDKs help you receive and respond to direct methods on devices without having to worry about the underlying protocol details.

MQTT

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

Method invocation

Devices receive direct method requests on the MQTT topic: $iothub/methods/POST/{method name}/?$rid={request id}. Однако request id не может быть известно заранее, так как Центр Интернета вещей создает его, следовательно, подпишитесь на $iothub/methods/POST/# и затем фильтруйте доставленные сообщения на основе поддерживаемых вашим устройством имен методов. (You use the generated request id to respond.)

The body that the device receives is in the following format:

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

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

Ответ

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

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

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

The device sets the body and can be any status.

AMQP

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

Method invocation

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

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

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

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

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

Ответ

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

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

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

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

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

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

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

• Планирование заданий на нескольких устройствах
• Azure IoT Hub SDKs перечислены различные языки SDK, которые можно использовать при разработке приложений для устройств и служб, взаимодействующих с Центром Интернета вещей.
• Язык запросов IoT Hub для двойников устройств, модулей, заданий и маршрутизации сообщений описывает язык запросов IoT Hub, который можно использовать для получения сведений о двойниках устройств и заданиях.