Examen de la administración de dispositivos mediante métodos directos en Azure IoT Hub

  • 5 minutos

IoT Hub ofrece la posibilidad de invocar métodos directos en dispositivos desde la nube. Los métodos directos representan una interacción solicitud-respuesta con un dispositivo similar a una llamada HTTP en la cual se completan correctamente o generan un error de inmediato (tras un tiempo de espera que especifica el usuario). Este enfoque es útil en escenarios donde el curso de una acción inmediata es distinto en función de si el dispositivo pudo responder.

Nota:

Para implementar métodos directos, debe ejecutar el nivel estándar del servicio IoT Hub.

Los métodos directos tienen las características siguientes:

  • Cada método directo tiene como destino un único dispositivo. Puede usar trabajos de IoT Hub para invocar métodos directos en varios dispositivos y programar la invocación de métodos para los dispositivos desconectados.
  • Cualquier persona con permisos de conexión de servicio en IoT Hub pueden invocar un método en un dispositivo.
  • Los métodos directos siguen un patrón de solicitud-respuesta y se usan para las comunicaciones que necesitan confirmación inmediata de su resultado. Por ejemplo, el control interactivo del dispositivo, como encender un ventilador.

Ciclo de vida de los métodos

Los métodos directos se implementan en el dispositivo y pueden requerir de ninguna entrada a varias en la carga de método para crear instancias correctamente. Se invoca un método directo mediante un URI orientado al servicio ({iot hub}/twins/{device id}/methods/). Un dispositivo recibe métodos directos a través de un tema MQTT específico del dispositivo ($iothub/methods/POST/{method name}/) o mediante vínculos AMQP (propiedades de la aplicación IoThub-methodname y IoThub-status).

Nota:

Cuando se invoca un método directo en un dispositivo, los valores y los nombres de propiedad solo pueden contener caracteres alfanuméricos US-ASCII imprimibles, excepto los del siguiente conjunto: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT.

Los métodos directos son sincrónicos y se completan correctamente o no después del período de tiempo de espera (valor predeterminado: 30 segundos, se puede establecer dentro del intervalo de 5 a 300 segundos). Los métodos directos son útiles en escenarios interactivos en los que quiere que un dispositivo actúe únicamente si está conectado y recibiendo comandos. Por ejemplo, encender una luz desde un teléfono. En estos escenarios, quiere saber de inmediato si la acción se ha completado o no para que el servicio en la nube pueda actuar lo antes posible en función del resultado. El dispositivo puede devolver un cuerpo de mensaje como resultado del método, pero no es necesario que el método lo haga. No hay ninguna garantía respecto al orden o la semántica de simultaneidad en las llamadas de método.

Los métodos directos son solo HTTP desde el lado de la nube y MQTT, AMQP, MQTT sobre WebSockets o AMQP sobre WebSockets desde el lado del dispositivo.

La carga útil de solicitudes y respuestas del método es un documento JSON de hasta 128 KB.

Invocación de un método directo desde una aplicación de back-end

Invocación de método

Las invocaciones de método directo en un dispositivo son llamadas HTTPS compuestas por los elementos siguientes:

  • El URI de solicitud específico del dispositivo junto con la versión de la API:

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

  • El método POST

  • Encabezados que contienen la autorización, el tipo de contenido y la codificación del contenido.

  • Un cuerpo JSON transparente en el formato siguiente:

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

El valor proporcionado como responseTimeoutInSeconds en la solicitud es la cantidad de tiempo que el servicio IoT Hub debe esperar a que finalice la ejecución de un método directo en un dispositivo. Configure este tiempo de espera para que sea al menos igual que el tiempo de ejecución esperado de un método directo por parte de un dispositivo. Si no se proporciona el tiempo de espera, se usa el valor predeterminado de 30 segundos. Los valores mínimo y máximo de responseTimeoutInSeconds son 5 y 300 segundos, respectivamente.

Ejemplo

A continuación se muestra un ejemplo sin sistema que usa curl.

  curl -X POST \
  https://iothubname.azure-devices.net/twins/myfirstdevice/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"
        }
    }'

Response

La aplicación de back-end recibe una respuesta que se compone de los siguientes elementos:

  • Código de estado HTTP, que se usa para errores procedentes de IoT Hub, incluido el error 404 para los dispositivos que no estén conectados.

  • Encabezados que contienen la etiqueta de identidad, el identificador de solicitud, el tipo de contenido y la codificación del contenido.

  • Un cuerpo JSON en el formato siguiente:

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

El dispositivo proporciona tanto status como body, que se utilizan para responder con el código de estado o la descripción propios del dispositivo.

Invocación de un método para los módulos de IoT Edge

Invocar métodos directos en un módulo es compatible con la API de REST del Método de invocar módulo o su equivalente en uno de los SDK de servicio de IoT Hub.

moduleId se pasa junto con en deviceId el URI de solicitud cuando se usa la API de REST o como parámetro cuando se usa un SDK de servicio. Por ejemplo, https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. El cuerpo y la respuesta de la solicitud son similares a los de los métodos directos invocados en el dispositivo.

Control de un método directo en un dispositivo

Un método directo en un dispositivo puede recibir solicitudes mediante los protocolos MQTT o AMQP.

MQTT

La sección siguiente es el protocolo MQTT.

Invocación de método

Los dispositivos reciben las solicitudes de método directo en el tema MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Sin embargo, request id se genera mediante IoT Hub y no se puede conocer con antelación, por lo que suscríbase a $iothub/methods/POST/# y filtre los mensajes entregados en función de los nombres de método admitidos por el dispositivo. (Usará el request id responder).

El cuerpo que recibe el dispositivo está en el formato siguiente:

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

Las solicitudes de método son QoS 0.

Response

El dispositivo envía las respuestas a $iothub/methods/res/{status}/?$rid={request id}, donde:

  • La propiedad status es el estado de la ejecución del método proporcionado por el dispositivo.
  • La propiedad $rid es el identificador de solicitud de la invocación de método recibido de IoT Hub.

El dispositivo establece el cuerpo y puede tener cualquier estado.

AMQP

La siguiente sección es para el protocolo AMQP.

Invocación de método

El dispositivo recibe solicitudes de método directo mediante la creación de un vínculo de recepción en la dirección amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Llega el mensaje AMQP en el vínculo de recepción que representa la solicitud del método. Contiene las secciones siguientes:

  • La propiedad del identificador de correlación, que contiene un identificador de solicitud que debe volver a pasarse con la respuesta del método correspondiente.
  • Una propiedad de la aplicación denominada IoThub-methodname, que contiene el nombre del método que se invoca.
  • El cuerpo del mensaje AMQP que contiene la carga del método como JSON.

Response

El dispositivo crea un vínculo para devolver la respuesta del método en la dirección amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

La respuesta del método se devuelve en el vínculo de envío y está estructurada de la siguiente manera:

  • La propiedad Id. de correlación, que contiene el identificador de solicitud pasado en el mensaje de solicitud del método.
  • Una propiedad de la aplicación denominada IoThub-status, que contiene el estado del método proporcionado por el usuario.
  • El cuerpo del mensaje AMQP que contiene la respuesta del método como JSON.