Envío y recepción de mensajes de la nube a dispositivo

Azure IoT Hub es un servicio totalmente administrado que permite la comunicación bidireccional, por ejemplo, mensajes de la nube al dispositivo (C2D) desde los back-end de la solución hasta millones de dispositivos.

En este artículo se describe cómo usar los SDK de Azure IoT para compilar los siguientes tipos de aplicaciones:

• Aplicaciones de dispositivo que reciben y controlan mensajes de la nube al dispositivo desde una cola de mensajería de IoT Hub.

• Aplicaciones de back-end que envían mensajes de la nube al dispositivo a un único dispositivo a través de una cola de mensajería de IoT Hub.

El objetivo de este artículo es servir de complemento a los ejemplos de SDK ejecutables a los que se hace referencia desde este artículo.

Nota:

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

Información general

Para que una aplicación de dispositivo reciba mensajes de la nube al dispositivo, debe conectarse a IoT Hub y, a continuación, configurar un controlador de mensajes para procesar los mensajes entrantes. Los SDK de dispositivo de Azure IoT Hub proporcionan clases y métodos que un dispositivo puede usar para recibir y controlar mensajes del servicio. En este artículo se describen los elementos clave de cualquier aplicación de dispositivo que reciba mensajes, entre los que se incluyen:

• Declaración de un objeto de cliente de dispositivo
• Conexión a IoT Hub
• Recuperación de mensajes de la cola de mensajes de IoT Hub
• Procesamiento del mensaje y envío de una confirmación a IoT Hub
• Configuración de una directiva de reintentos de recepción de mensajes

Para que una aplicación de back-end envíe mensajes de la de nube al dispositivo, debe conectarse a IoT Hub y enviar mensajes a través de una cola de mensajes de IoT Hub. Los SDK del servicio Azure IoT Hub proporcionan clases y métodos que una aplicación puede usar para enviar mensajes a los dispositivos. En este artículo se describen los elementos clave de cualquier aplicación que envíe mensajes a dispositivos, entre los que se incluyen:

• Declaración de un objeto de cliente de servicio
• Conexión a IoT Hub
• Compilación y envío del mensaje
• Recepción de comentarios de entrega
• Configuración de una directiva de reintentos de envío de mensajes

Descripción de la cola de mensajes

Para comprender la mensajería de la nube al dispositivo, es importante comprender algunos aspectos básicos sobre cómo funcionan las colas de mensajes de dispositivo IoT Hub.

Los mensajes de la nube al dispositivo enviados desde una aplicación de back-end de solución a un dispositivo IoT se enrutan a través de IoT Hub. No hay ninguna comunicación directa de mensajería punto a punto entre una aplicación de back-end de solución y el dispositivo de destino. IoT Hub coloca los mensajes entrantes en su cola de mensajes, listos para que los descarguen los dispositivos IoT de destino.

Para garantizar la entrega de mensajes al menos una vez, IoT Hub conserva los mensajes de la nube al dispositivo en colas por dispositivo. Los dispositivos deben confirmar explícitamente la finalización de un mensaje antes de que IoT Hub quite el mensaje de la cola. Esto garantiza la resistencia frente a errores de dispositivo y de conectividad.

Cuando IoT Hub coloca un mensaje en una cola de mensajes de dispositivo, establece el estado del mensaje en En cola. Cuando un subproceso de dispositivo toma un mensaje de la cola, IoT Hub bloquea el mensaje estableciendo el estado del mensaje en Invisible. Este estado impide que otros subprocesos del dispositivo procesen el mismo mensaje. Cuando un subproceso de dispositivo completa correctamente el procesamiento de un mensaje, notifica a IoT Hub y, a continuación, IoT Hub establece el estado del mensaje en Completado.

Una aplicación de dispositivo que recibe y procesa correctamente un mensaje se dice que completa el mensaje. Sin embargo, si es necesario, un dispositivo también puede hacer lo siguiente:

• Rechazar el mensaje, lo que hace que IoT Hub lo establezca en estado "En la cola de mensajes fallidos". Los dispositivos que se conectan mediante el protocolo Message Queuing Telemetry Transport (MQTT) no pueden rechazar mensajes de la nube al dispositivo.
• Abandonar el mensaje, lo que hace que IoT Hub vuelva a ponerlo en la cola con el estado del mensaje establecido en En cola. Los dispositivos que se conectan mediante el protocolo MQTT no pueden abandonar mensajes de la nube al dispositivo.

Para más información sobre el ciclo de vida de los mensajes de la nube al dispositivo y sobre cómo IoT Hub procesa los mensajes de nube a dispositivo, consulte Enviar mensajes de nube a dispositivo desde un IoT Hub.

Recepción de mensajes de nube a dispositivo

En esta sección se describe cómo recibir mensajes de la nube al dispositivo mediante la clase DeviceClient en el SDK de Azure IoT para .NET.

Hay dos opciones que la aplicación cliente de un dispositivo puede usar para recibir mensajes:

• Sondeo: la aplicación de dispositivo comprueba si hay nuevos mensajes de IoT Hub mediante un bucle de código (por ejemplo, un bucle whileo for). El bucle se ejecuta continuamente y va comprobado si hay mensajes.
• Devolución de llamada: la aplicación de dispositivo configura un método de controlador de mensajes asincrónico al que se llama inmediatamente cuando llega un mensaje.

Declaración de un objeto DeviceClient

DeviceClient incluye métodos y propiedades necesarios para recibir mensajes de IoT Hub.

Por ejemplo:

static DeviceClient deviceClient;

Suministro de los parámetros de conexión

Proporcione la cadena de conexión principal de IoT Hub y el identificador de dispositivo a DeviceClient para usar el método CreateFromConnectionString. Además de la cadena de conexión principal de IoT Hub necesaria, el método CreateFromConnectionString se puede sobrecargar para incluir estos parámetros opcionales:

• transportType: el protocolo de transporte (variaciones de la versión HTTP 1, AMQP o MQTT). AMQP es el valor predeterminado. Para ver todos los valores disponibles, consulte TransportType (enumeración).
• transportSettings: interfaz que se usa para definir varias configuraciones específicas del transporte para DeviceClient y ModuleClient. Para más información, consulte ITransportSettings (interfaz).
• ClientOptions: opciones que permiten la configuración de la instancia de cliente del dispositivo o del módulo durante la inicialización.

En este ejemplo se llama a CreateFromConnectionString para definir la configuración de IoT Hub y de la identidad del dispositivo de la conexión DeviceClient.

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

Sondeo

El sondeo usa ReceiveAsync para buscar mensajes.

Una llamada a ReceiveAsync puede adoptar estas formas:

• ReceiveAsync(): aguardar el período de tiempo de espera predeterminado para un mensaje antes de continuar.
• ReceiveAsync (Timespan): recibir un mensaje de la cola de dispositivos mediante un tiempo de espera específico.
• ReceiveAsync (CancellationToken): recibir un mensaje de la cola de dispositivos mediante un token de cancelación. Cuando se usa un token de cancelación, no se utiliza el período de tiempo de espera predeterminado.

Cuando se usa un tipo de transporte de HTTP 1 en lugar de MQTT o AMQP, el método ReceiveAsync se devuelve inmediatamente. El patrón admitido para los mensajes de la nube al dispositivo con HTTP 1 es el de dispositivos conectados de forma intermitente que comprueban si hay mensajes con poca frecuencia (cada 25 minutos como mínimo). Emitir más solicitudes HTTP 1 resulta en que IoT Hub las limite. Para más información sobre las diferencias entre la compatibilidad con MQTT, AMQP y HTTP 1, consulte Guía de comunicación de la nube al dispositivo y Selección de un protocolo de comunicación.

CompleteAsync (método)

Una vez que el dispositivo recibe un mensaje, la aplicación de dispositivo llama al método CompleteAsync para notificar a IoT Hub que el mensaje se ha procesado correctamente y que, por tanto, se puede quitar de forma segura de la cola de dispositivos IoT Hub. El dispositivo debe llamar a este método cuando el procesamiento se complete correctamente, independientemente del protocolo que utilice.

Abandono, rechazo o tiempo de espera de mensajes

Con los protocolos AMQP y HTTP versión 1, pero no con el protocolo MQTT, el dispositivo también puede:

• Abandonar un mensaje llamando a AbandonAsync. Como resultado, IoT Hub retiene el mensaje en la cola del dispositivo para su futuro consumo.
• Rechazar un mensaje llamando a RejectAsync. Como resultado, el mensaje se quita permanentemente de la cola del dispositivo.

Si se produce algo que impide que el dispositivo complete, abandone o rechace el mensaje, IoT Hub, después de un período de tiempo de espera fijo, lo pone en cola para repetir la entrega. Por este motivo, la lógica de procesamiento de mensajes de la aplicación del dispositivo debe ser idempotente, de modo que, si se recibe el mismo mensaje varias veces, se genere el mismo resultado.

Para más información sobre el ciclo de vida de los mensajes de la nube al dispositivo y sobre cómo IoT Hub procesa los mensajes de nube a dispositivo, consulte Enviar mensajes de nube a dispositivo desde un IoT Hub.

Bucle de sondeo

Con el sondeo, una aplicación usa un bucle de código que llama al método ReceiveAsync de forma repetida para comprobar si hay nuevos mensajes hasta que se detiene.

Si se usa ReceiveAsync con un valor de tiempo de espera o el tiempo de espera predeterminado, en el bucle cada llamada a ReceiveAsync espera el período de tiempo de espera especificado. Si ReceiveAsync agota el tiempo de espera, se devuelve un valor null y el bucle continúa.

Cuando se recibe un mensaje, ReceiveAsync devuelve un objeto Task que debe pasarse a CompleteAsync. Una llamada a CompleteAsync notifica a IoT Hub que elimine el mensaje especificado de la cola de mensajes en función del parámetro Task.

En este ejemplo, el bucle llama a ReceiveAsync hasta que se recibe un mensaje o se detiene el bucle de sondeo.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Devolución de llamada

Para recibir mensajes de devolución de llamada de la nube al dispositivo en la aplicación de dispositivo, la aplicación debe conectarse a IoT Hub y configurar un cliente de escucha de devolución de llamada para procesar los mensajes entrantes. Los mensajes que entran al dispositivo se reciben desde la cola de mensajes de IoT Hub.

Con la devolución de llamada, la aplicación de dispositivo configura un método de controlador de mensajes mediante SetReceiveMessageHandlerAsync. A continuación, se llama al controlador de mensajes y se recibe un mensaje. La creación de un método de devolución de llamada para recibir mensajes elimina la necesidad de sondear continuamente los mensajes recibidos.

La devolución de llamada solo está disponible con estos protocolos:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_only

La opción de protocolo Http1 no admite devoluciones de llamada, ya que los métodos del SDK necesitarían sondear los mensajes recibidos de todos modos, lo que acaba con el principio de devolución de llamada.

En este ejemplo, SetReceiveMessageHandlerAsync configura un método de controlador de devolución de llamada denominado OnC2dMessageReceivedAsync, al que se llama cada vez que se recibe un mensaje.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

Directiva de reintentos de recepción de mensajes

La directiva de reintentos de recepción de mensajes de cliente del dispositivo se puede definir mediante DeviceClient.SetRetryPolicy.

El tiempo de espera de reintento del mensaje se almacena en la propiedad DeviceClient.OperationTimeoutInMilliseconds.

Ejemplo de recepción de mensajes del SDK

El SDK de .NET o C# incluye un ejemplo de recepción de mensajes con los métodos de recepción de mensaje descritos en esta sección.

Envío de mensajes de nube a dispositivo

En esta sección se describe el código esencial para enviar un mensaje desde la aplicación de back-end de una solución hasta un dispositivo IoT mediante la clase ServiceClient del SDK de Azure IoT para .NET. Como se ha descrito anteriormente, la aplicación de back-end de una solución se conecta a una instancia de IoT Hub y los mensajes se envían a IoT Hub codificados con un dispositivo de destino. IoT Hub almacena los mensajes entrantes en su cola de mensajes y los mensajes se entregan desde la cola de mensajes de IoT Hub hasta el dispositivo de destino.

Una aplicación de back-end de solución también puede solicitar y recibir comentarios de entrega de un mensaje enviado a IoT Hub destinado a la entrega en el dispositivo a través de la cola de mensajes.

Declaración de un objeto ServiceClient

ServiceClient incluye métodos y propiedades necesarios para enviar mensajes desde una aplicación hasta un dispositivo a través de IoT Hub.

static ServiceClient serviceClient;

Suministro de la cadena de conexión

Proporcione la cadena de conexión principal de IoT Hub a ServiceClient para usar el método CreateFromConnectionString. Además de la cadena de conexión principal de IoT Hub necesaria, el método CreateFromConnectionString se puede sobrecargar para incluir estos parámetros opcionales:

• transportType - Amqp o Amqp_WebSocket_Only.
• transportSettings: la configuración del proxy de AMQP y HTTP para el cliente de servicio.
• ServiceClientOptions: opciones que permiten la configuración de la instancia de cliente de servicio durante la inicialización. Para más información, consulte ServiceClientOptions.

En este ejemplo se crea el objeto ServiceClient mediante la cadena de conexión de IoT Hub.

static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Envío de un mensaje asincrónico de la nube al dispositivo

Use sendAsync para enviar un mensaje asincrónico desde una aplicación hasta el dispositivo mediante la nube (IoT Hub). La llamada se realiza mediante el protocolo AMQP.

sendAsync usa estos parámetros:

• deviceID: identificador de la cadena del dispositivo de destino.
• message: mensaje de la nube al dispositivo. El mensaje es de tipo Message y se puede formatear en consecuencia.
• timeout: un valor de tiempo de espera opcional. El valor predeterminado es un minuto si no se especifica.

En este ejemplo se envía un mensaje de prueba al dispositivo de destino con un valor de tiempo de espera de 10 segundos.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

Recepción de comentarios de entrega

Un programa de envío puede solicitar confirmaciones de entrega (o expiración) a IoT Hub para cada mensaje de la nube al dispositivo. Esta opción permite al programa de envío usar la lógica de información, reintento o compensación. Una descripción completa de las operaciones y propiedades de comentarios de mensajes se describen en Comentarios de mensajes.

Para recibir comentarios de entrega de mensajes:

• Cree el objeto feedbackReceiver
• Envío de mensajes mediante el parámetro Ack
• Esperar para recibir comentarios

Creación del objeto feedbackReceiver

Llame a GetFeedbackReceiver para crear un objeto FeedbackReceiver. FeedbackReceiver contiene métodos que los servicios pueden usar para realizar operaciones de recepción de comentarios.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Envío de mensajes mediante el parámetro Ack

Cada mensaje debe incluir un valor para la propiedad Ack de confirmación de entrega para recibir comentarios de entrega. La propiedad Ack puede tener uno de estos valores:

• none (valor predeterminado): no se genera ningún mensaje de comentarios.

• Positive: se recibe un mensaje de comentarios si el mensaje se ha completado.

• Negative: se recibe un mensaje de comentarios si el mensaje ha expirado (o se ha alcanzado el número máximo de entregas) sin que el dispositivo lo complete.

• Full: comentarios para los resultados Positive y Negative.

En este ejemplo, la propiedad Ack se establece en Full, que solicita comentarios de entrega de mensajes positivos o negativos para un mensaje.

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

Esperar para recibir comentarios

Defina un valor para CancellationToken. A continuación, en un bucle, llame a ReceiveAsync de forma repetida y compruebe si hay mensajes de comentarios de entrega. Cada llamada a ReceiveAsync espera el período de tiempo de espera definido para el objeto ServiceClient.

• Si un tiempo de espera de ReceiveAsync expira sin recibir ningún mensaje, ReceiveAsync devuelve null y el bucle continúa.
• Si se recibe un mensaje de comentarios, ReceiveAsync devuelve un objeto Task que se debe pasar a CompleteAsync junto con el token de cancelación. Una llamada a CompleteAsync elimina el mensaje enviado especificado de la cola de mensajes en función del parámetro Task.
• Si es necesario, el código de recepción puede llamar a AbandonAsync para devolver un mensaje de envío en la cola.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

En este ejemplo se muestra un método que incluye estos pasos.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

Tenga en cuenta que este patrón de recepción de comentarios es similar al patrón que se usa para recibir mensajes de la nube al dispositivo en la aplicación de dispositivo.

Reconexión del cliente de servicio

Si encuentra una excepción, el cliente de servicio retransmite esa información a la aplicación que realiza la llamada. En ese momento, se recomienda inspeccionar los detalles de la excepción y tomar las medidas necesarias.

Por ejemplo:

• Si se trata de una excepción de red, puede volver a intentar la operación.
• Si se trata de una excepción de seguridad (excepción no autorizada), inspeccione las credenciales y asegúrese de que están actualizadas.
• Si se trata de una excepción de limitación o cuota superada, supervise o modifique la frecuencia de solicitudes de envío o actualice la unidad de escalado de instancias del centro. Consulte Cuotas y limitación de IoT Hub para más información.

Directiva de reintentos de envío de mensajes

La directiva de reintentos de mensajes ServiceClient se puede definir mediante ServiceClient.SetRetryPolicy.

Ejemplo de envío de mensajes del SDK

El SDK de .NET o C# incluye un ejemplo de cliente de servicio que incluye los métodos de envío de mensajes descritos en esta sección.

Recepción de mensajes de nube a dispositivo

En esta sección se describe cómo recibir mensajes de la nube al dispositivo mediante la clase DeviceClient del SDK de Azure IoT para Java.

Para que una aplicación de dispositivo basada en Java reciba mensajes de la nube al dispositivo, debe conectarse a IoT Hub y, a continuación, configurar un cliente de escucha de devolución de llamada y un controlador de mensajes para procesar mensajes entrantes desde IoT Hub. La aplicación de dispositivo también debe poder detectar y controlar las desconexiones en caso de que se interrumpa la conexión de mensajes del dispositivo a IoT Hub.

Importación de bibliotecas del SDK de Java en Azure IoT

El código al que se hace referencia en este artículo usa estas bibliotecas del SDK.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

Declaración de un objeto DeviceClient

La creación de instancias del objeto DeviceClient requiere estos parámetros:

• connString: la cadena de conexión del dispositivo IoT. La cadena de conexión es un conjunto de pares clave-valor separados por ";", con las claves y los valores separados por "=". Debe contener valores para estas claves: HostName, DeviceId, and SharedAccessKey.
• Protocolo de transporte: la conexión DeviceClient puede usar uno de los siguientes protocolos de transporte IoTHubClientProtocol. AMQP es el más versátil; permite comprobar los mensajes con frecuencia y el rechazo y la cancelación de mensajes. MQTT no admite métodos de rechazo o abandono de mensajes:
  • AMQPS
  • AMQPS_WS
  • HTTPS
  • MQTT
  • MQTT_WS

Por ejemplo:

static string connectionString = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

Establecimiento del método de devolución de llamada de mensajes

Use el método setMessageCallback para definir un método de controlador de mensajes que se notifica cuando se recibe un mensaje de IoT Hub.

setMessageCallback incluye estos parámetros:

• callback: nombre del método de devolución de llamada. Puede ser null.
• context: un contexto opcional de tipo object. Si no se especifica, use null.

En este ejemplo, se pasa un método callback denominado MessageCallback sin parámetro de contexto a setMessageCallback.

client.setMessageCallback(new MessageCallback(), null);

Creación de un controlador de devolución de llamada de mensajes

Un controlador de mensajes de devolución de llamada recibe y procesa un mensaje entrante pasado desde la cola de mensajes de IoT Hub.

En este ejemplo, el controlador de mensajes procesa un mensaje entrante y, a continuación, devuelve IotHubMessageResult.COMPLETE. Un valor de retorno IotHubMessageResult.COMPLETE notifica a IoT Hub que el mensaje se ha procesado correctamente y que se puede quitar de la cola del dispositivo de forma segura. El dispositivo debe devolver IotHubMessageResult.COMPLETE cuando el procesamiento se complete correctamente, y notificar a IoT Hub que el mensaje se debe quitar de la cola de mensajes, independientemente del protocolo que use.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

Opciones de abandono y rechazo de mensajes

Aunque el gran número de mensajes entrantes a un dispositivo debería recibirse correctamente y tener como resultado el mensaje IotHubMessageResult.COMPLETE, puede ser necesario abandonar o rechazar un mensaje.

• Con AMQP y HTTPS, pero no MQTT, una aplicación puede:
  • Abandonar el mensaje (IotHubMessageResult.ABANDON). IoT Hub vuelve a ponerlo en cola y lo envía de nuevo más tarde.
  • Rechazar el mensaje (IotHubMessageResult.REJECT). IoT Hub no vuelve a poner en cola el mensaje y lo quita permanentemente de la cola de mensajes.
• Los clientes que usan MQTT o MQTT_WS no pueden abandonar (ABANDON) ni rechazar (REJECT) mensajes.

Si se produce algo que impide que el dispositivo complete, abandone o rechace el mensaje, IoT Hub, después de un período de tiempo de espera fijo, lo pone en cola para repetir la entrega. Por este motivo, la lógica de procesamiento de mensajes de la aplicación del dispositivo debe ser idempotente, de modo que, si se recibe el mismo mensaje varias veces, se genere el mismo resultado.

Para más información sobre el ciclo de vida de los mensajes de la nube al dispositivo y sobre cómo IoT Hub procesa los mensajes de nube a dispositivo, consulte Enviar mensajes de nube a dispositivo desde un IoT Hub.

Nota

Si usa HTTPS en lugar de MQTT o AMQP como transporte, la instancia DeviceClient busca mensajes de IoT Hub con menos frecuencia (cada 25 minutos como mínimo). Para más información sobre las diferencias entre la compatibilidad con MQTT, AMQP y HTTPS, consulte Guía de comunicación de nube a dispositivo y Elección de un protocolo de comunicación.

Creación del método de devolución de llamada de estado del mensaje

Una aplicación puede usar registerConnectionStatusChangeCallback para registrar un método de devolución de llamada que se ejecute cuando cambie el estado de conexión del dispositivo. De este modo, la aplicación puede detectar una conexión de mensajes inactiva e intentar volver a conectarse.

En este ejemplo, IotHubConnectionStatusChangeCallbackLogger se registra como método de devolución de llamada de cambio del estado de la conexión.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

La devolución de llamada se desencadena y se pasa un objeto ConnectionStatusChangeContext.

Llame a connectionStatusChangeContext.getNewStatus() para obtener el estado de conexión actual.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

El estado de conexión devuelto puede ser uno de estos valores:

• IotHubConnectionStatus.DISCONNECTED
• IotHubConnectionStatus.DISCONNECTED_RETRYING
• IotHubConnectionStatus.CONNECTED

Llamar a connectionStatusChangeContext.getNewStatusReason() para obtener el motivo del cambio de estado de la conexión.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Llamar a connectionStatusChangeContext.getCause() para encontrar el motivo del cambio de estado de la conexión. getCause() puede devolver null si no hay información disponible.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

Consulte el ejemplo HandleMessages que se muestra en la sección de ejemplo de recepción de mensajes del SDK de este artículo para ver un ejemplo completo que muestra cómo extraer el método de devolución de llamada de cambio de estado de la conexión, el motivo por el que cambió el estado del dispositivo y el contexto.

Apertura de la conexión entre el dispositivo e IoT Hub

Use open para crear una conexión entre el dispositivo e IoT Hub. El dispositivo ahora puede enviar y recibir mensajes de forma asincrónica hacia y desde una instancia de IoT Hub. Si el cliente ya está abierto, el método no hace nada.

client.open(true);

Ejemplo de recepción de mensajes del SDK

HandleMessages: una aplicación de dispositivo de ejemplo incluida con el SDK de IoT de Microsoft Azure para Java, que se conecta al centro de IoT y recibe mensajes de la nube al dispositivo.

Envío de mensajes de nube a dispositivo

En esta sección se describe cómo enviar un mensaje de la nube al dispositivo mediante la clase ServiceClient desde el SDK de Azure IoT para Java. Una aplicación de back-end de solución se conecta a una instancia de IoT Hub y los mensajes se envían a IoT Hub codificados con un dispositivo de destino. IoT Hub almacena los mensajes entrantes en su cola de mensajes y los mensajes se entregan desde la cola de mensajes de IoT Hub hasta el dispositivo de destino.

Una aplicación de back-end de solución también puede solicitar y recibir comentarios de entrega de un mensaje enviado a IoT Hub destinado a la entrega en el dispositivo a través de la cola de mensajes.

Adición de la instrucción de dependencia

Agregue la dependencia para usar el paquete iothub-java-service-client en la aplicación para comunicarse con el servicio IoT Hub:

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

Adición de instrucciones import

Agregue estas instrucciones import para usar el SDK de Java en Azure IoT y el controlador de excepciones.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Definición del protocolo de conexión

Use IotHubServiceClientProtocol para definir el protocolo de la capa de aplicación usado por el cliente de servicio para comunicarse con una instancia de IoT Hub.

IotHubServiceClientProtocol solo acepta la enumeración AMQPS o AMQPS_WS.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Creación del objeto ServiceClient

Cree el objeto ServiceClient y proporcione la cadena de conexión y el protocolo de Iot Hub.

private static final String connectionString = "{yourhubconnectionstring}";
private static final ServiceClient serviceClient (connectionString, protocol);

Apertura de la conexión entre la aplicación e IoT Hub

Abrir la conexión del remitente de AMQP. Este método crea la conexión entre la aplicación y IoT Hub.

serviceClient.open();

Abrir un receptor de comentarios para los comentarios de entrega de mensajes

Puede usar FeedbackReceiver para obtener comentarios sobre la entrega de mensajes enviados a de IoT Hub. FeedbackReceiver es un receptor especializado cuyo método Receive devuelve FeedbackBatch en lugar de Message.

En este ejemplo, se crea el objeto FeedbackReceiver y se llama a la instrucción open() para esperar comentarios.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

Adición de propiedades del mensaje

Opcionalmente, puede usar setProperties para agregar propiedades de mensaje. Estas propiedades se incluyen en el mensaje enviado al dispositivo y la aplicación del dispositivo puede extraerlas tras la recepción.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Creación y envío de un mensaje asincrónico

El objeto Message almacena el mensaje que se va a enviar. En este ejemplo, se entrega un mensaje de la nube al dispositivo.

Use setDeliveryAcknowledgement para solicitar la confirmación de entregado/no entregado a la cola de mensajes de IoT Hub. En este ejemplo, la confirmación solicitada es Full, ya sea entregado o no entregado.

Use SendAsync para enviar un mensaje asincrónico del cliente al dispositivo. Como alternativa, puede usar el método Send (no asincrónico), pero esta función se sincroniza internamente para que solo se permita una operación de envío a la vez. El mensaje se entrega desde la aplicación hasta IoT Hub. IoT Hub coloca el mensaje en la cola de mensajes, listo para entregarse al dispositivo de destino.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

Comentarios de entrega de recepción de mensajes

Después de enviar un mensaje desde la aplicación, la aplicación puede llamar a receive con o sin un valor de tiempo de espera. Si no se proporciona un valor de tiempo de espera, se usa el tiempo de espera predeterminado. Se devuelve un objeto FeedbackBatch que contiene las propiedades de comentarios de entrega de mensajes que se pueden examinar.

En este ejemplo se crea el receptor FeedbackBatch y se llama a getEnqueuedTimeUtc, que imprime la hora de puesta en cola del mensaje.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

Ejemplos de envío de mensajes del SDK

• Ejemplo de cliente de servicio: ejemplo de envío de mensajes, 1.

• Ejemplo de cliente de servicio: ejemplo de envío de mensajes, 2.

Instalación de la biblioteca del SDK de Azure IoT

Instale la biblioteca del SDK azure-iot-device en la máquina de desarrollo antes de llamar a cualquier código relacionado:

pip install azure-iot-device

Hay dos clases del SDK de Python que se usan para enviar mensajes a dispositivos IoT y desde ellos. Los métodos de control de mensajes de estas clases se describen en las secciones de esta página.

• La clase IoTHubDeviceClient incluye métodos para crear una conexión sincrónica desde un dispositivo hasta una instancia de Azure IoT Hub y recibir mensajes de IoT Hub.

• La clase IoTHubRegistryManager incluye API para las operaciones del Administrador del Registro de IoT Hub. En este artículo, los métodos de esta clase muestran cómo conectarse a IoT Hub y enviar un mensaje a un dispositivo.

Recepción de mensajes de nube a dispositivo

En esta sección se describe cómo recibir mensajes de la nube al dispositivo mediante la clase IoTHubDeviceClient del SDK de Azure IoT para Python.

Para que una aplicación de dispositivo basada en Python reciba mensajes de la nube al dispositivo, debe conectarse a IoT Hub y, a continuación, configurar un controlador de mensajes de devolución de llamada para procesar los mensajes entrantes desde IoT Hub.

Importación del objeto IoTHubDeviceClient

Agregue una línea de código para importar las funciones IoTHubDeviceClient desde el SDK azure.iot.device.

from azure.iot.device import IoTHubDeviceClient

Conexión del cliente del dispositivo

Cree una instancia de IoTHubDeviceClienty pase una cadena de conexión de IoT Hub a create_from_connection_string. Se crea una conexión desde el dispositivo hasta IoT Hub.

Como alternativa, puede conectar IoTHubDeviceClient a un dispositivo mediante uno de estos métodos:

• Cadena de token de SAS
• Autenticación de clave simétrica
• Autenticación de certificados X.509

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

Control de la reconexión

IoTHubDeviceClient intentará restablecer de forma predeterminada una conexión descartada. El comportamiento de reconexión se rige por los parámetros IoTHubDeviceClient connection_retry y connection_retry_interval.

Creación de un controlador de mensajes

Cree la función de controlador de mensajes para procesar los mensajes entrantes al dispositivo.

En este ejemplo, se llama a message_handler cuando se recibe un mensaje. Las propiedades del mensaje (.items) se imprimen en la consola mediante un bucle.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

Asignación del controlador de mensajes

Use el método on_message_received para asignar el método de controlador de mensajes al objeto IoTHubDeviceClient.

En este ejemplo, se adjunta un método de controlador de mensajes denominado message_handler al objeto client IoTHubDeviceClient. El objeto client espera a recibir un mensaje de la nube al dispositivo de una instancia de IoT Hub. Este código espera hasta 300 segundos (5 minutos) un mensaje o se cierra si se presiona una tecla del teclado.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

Ejemplo de recepción de mensajes del SDK

Recepción de mensajes: recepción de mensajes de la nube al dispositivo (C2D) enviados desde Azure IoT Hub a un dispositivo.

Envío de mensajes de nube a dispositivo

En esta sección se describe cómo enviar un mensaje de la nube al dispositivo mediante la clase IoTHubRegistryManager desde el SDK de Azure IoT para Python. Una aplicación de back-end de solución se conecta a una instancia de IoT Hub y los mensajes se envían a IoT Hub codificados con un dispositivo de destino. IoT Hub almacena los mensajes entrantes en su cola de mensajes y los mensajes se entregan desde la cola de mensajes de IoT Hub hasta el dispositivo de destino.

Importación del objeto IoTHubRegistryManager

Agregue la siguiente instrucción import . IoTHubRegistryManager incluye API para las operaciones del Administrador del Registro de IoT Hub.

from azure.iot.hub import IoTHubRegistryManager

Conexión del Administrador del Registro de IoT Hub

Cree una instancia del objeto IoTHubRegistryManager que se conecta a una instancia de IoT Hub y pase una cadena de conexión de IoT Hub a from_connection_string.

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

Compilación y envío de un mensaje

Use send_c2d_message para enviar un mensaje al dispositivo a través de la nube (IoT Hub).

send_c2d_message usa estos parámetros:

• deviceID: identificador de la cadena del dispositivo de destino.
• message: mensaje de la nube al dispositivo. El mensaje es de tipo str (cadena).
• properties : colección opcional de propiedades de tipo dict. Las propiedades pueden contener propiedades de aplicación y propiedades del sistema. El valor predeterminado es {}.

En este ejemplo se envía un mensaje de prueba al dispositivo de destino.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

Ejemplo de envío de mensajes del SDK

send_message.py: muestra cómo enviar un mensaje de la nube al dispositivo.

Instalación de los paquetes de mensajería de Node.js

Ejecute estos comandos para instalar los paquetes azure-iot-device y azure-iothub en la máquina de desarrollo:

npm install azure-iot-device --save
npm install azure-iothub --save

El paquete azure-iot-device contiene objetos que interactúan con dispositivos IoT. En este artículo se describe el código de clase Client que recibe mensajes de IoT Hub.

El paquete azure-iothub contiene objetos que interactúan con IoT Hub. En este artículo se describe el código de clase Client que envía un mensaje de una aplicación a un dispositivo a través de IoT Hub.

Recepción de mensajes en la aplicación de dispositivo

En esta sección se describe cómo recibir mensajes de la nube al dispositivo mediante el paquete azure-iot-device del SDK de Azure IoT para Node.js.

Para que una aplicación de dispositivo basada en Node.js reciba mensajes de la nube al dispositivo, debe conectarse a IoT Hub y, a continuación, configurar un cliente de escucha de devolución de llamada y un controlador de mensajes para procesar mensajes entrantes desde IoT Hub. La aplicación de dispositivo también debe poder detectar y controlar las desconexiones en caso de que se interrumpa la conexión de mensajes del dispositivo a IoT Hub.

Creación de un módulo de cliente

En el paquete azure-iot-device, cree un objeto Client mediante la clase Client. La clase Client contiene métodos que un dispositivo puede usar para recibir de IoT Hub y enviar a este.

const Client = require('azure-iot-device').Client;

Selección de un protocolo de transporte

EClientl objeto admite estos protocolos:

• Amqp
• Http: al usar Http, la instancia de Client comprueba si hay mensajes de IoT Hub con poca frecuencia (cada 25 minutos como mínimo).
• Mqtt
• MqttWs
• AmqpWs

Para más información sobre las diferencias entre la compatibilidad con MQTT, AMQP y HTTPS, consulte Guía de comunicación de nube a dispositivo y Elección de un protocolo de comunicación.

En este ejemplo se asigna el protocolo AMQP a una variable Protocol. Esta variable Protocol se pasa al método Client.fromConnectionString de la sección Adición de la cadena de conexión de este artículo.

const Protocol = require('azure-iot-device-mqtt').Amqp;

Funcionalidades de finalización, rechazo y abandono de mensajes

Los métodos de finalización, rechazo y abandono de mensajes se pueden usar en función del protocolo elegido.

AMQP y HTTP

Los transportes AMQP y HTTP pueden completar, rechazar o abandonar un mensaje:

• Completado: para completar un mensaje, el servicio que envió el mensaje de la nube al dispositivo recibe una notificación de que el mensaje se ha recibido. IoT Hub quita el mensaje de la cola de mensajes. El método adopta la forma de client.complete(message, callback function).
• Rechazar: para rechazar un mensaje, el servicio que envió el mensaje de la nube al dispositivo recibe una notificación de que el dispositivo no ha procesado el mensaje. IoT Hub quita permanentemente el mensaje de la cola de dispositivos. El método adopta la forma de client.reject(message, callback function).
• Abandonar: para abandonar un mensaje, IoT Hub intenta volver a enviarlo inmediatamente. IoT Hub conserva el mensaje en la cola de dispositivos para su consumo futuro. El método adopta la forma de client.abandon(message, callback function).

MQTT

MQTT no admite funciones de finalización, rechazo o abandono de mensajes. En su lugar, MQTT acepta un mensaje de forma predeterminada y el mensaje se quita de la cola de mensajes de IoT Hub.

Intentos de nueva entrega

Si se produce algo que impide que el dispositivo complete, abandone o rechace el mensaje, IoT Hub, después de un período de tiempo de espera fijo, lo pone en cola para repetir la entrega. Por este motivo, la lógica de procesamiento de mensajes de la aplicación del dispositivo debe ser idempotente, de modo que, si se recibe el mismo mensaje varias veces, se genere el mismo resultado.

Adición de la cadena y el protocolo de transporte de IoT Hub

Llame a fromConnectionString para establecer una conexión de dispositivo a IoT Hub mediante estos parámetros:

• connStr: una cadena de conexión que encapsula los permisos "device connect" para una instancia de IoT Hub. La cadena de conexión contiene el nombre de host, la identidad del dispositivo y la clave de acceso compartido en este formato: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
• transportCtor: el protocolo de transporte.

const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Creación de un controlador de mensajes entrantes

Se llama al controlador de mensajes para cada mensaje entrante.

Después de recibir correctamente un mensaje, si se usa el transporte AMQP o HTTP, llame al método client.complete para informar a IoT Hub de que el mensaje se puede quitar de la cola de mensajes.

Por ejemplo, este controlador de mensajes imprime el identificador de mensaje y el cuerpo del mensaje en la consola y, a continuación, llama a client.complete para notificar a IoT Hub que ha procesado el mensaje y que se puede quitar de la cola de dispositivos de forma segura. La llamada a completeno es necesaria si se usa el transporte MQTT y se puede omitir. Se requiere una llamada a complete para el transporte AMQP o HTTPS.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

Creación de un controlador de desconexión de la conexión

Se llama al controlador de desconexión cuando se desconecta la conexión. Un controlador de desconexión es útil para implementar código de reconexión.

En este ejemplo se detecta y se muestra el mensaje de error de desconexión en la consola.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

Adición de clientes de escucha de eventos

Puede especificar estos clientes de escucha de eventos mediante el método .on.

• Controlador de conexión
• Controlador de errores
• Desconexión del controlador
• Controlador de mensajes

En este ejemplo se incluyen los controladores de mensajes y de desconexión definidos anteriormente.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

Apertura de la conexión a IoT Hub

Use el método open para abrir una conexión entre un dispositivo IoT e IoT Hub. Use .catch(err) para detectar un código de controlador de errores y llamadas.

Por ejemplo:

client.open()
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Ejemplo de recepción de mensajes del SDK

simple_sample_device: una aplicación de dispositivo que se conecta a la instancia de IoT Hub y recibe mensajes de la nube al dispositivo.

Envío de mensajes de nube a dispositivo

En esta sección se describe cómo enviar un mensaje de la nube al dispositivo mediante el paquete azure-iothub del SDK de Azure IoT para Node.js. Como se ha descrito anteriormente, la aplicación de back-end de una solución se conecta a una instancia de IoT Hub y los mensajes se envían a IoT Hub codificados con un dispositivo de destino. IoT Hub almacena los mensajes entrantes en su cola de mensajes y los mensajes se entregan desde la cola de mensajes de IoT Hub hasta el dispositivo de destino.

Una aplicación de back-end de solución también puede solicitar y recibir comentarios de entrega de un mensaje enviado a IoT Hub destinado a la entrega en el dispositivo a través de la cola de mensajes.

Carga de los módulos de cliente y de mensajes

Declare un objeto Client mediante la clase Client del paquete azure-iothub.

Declare un objeto Message mediante la clase Message del paquete azure-iot-common.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

Creación del objeto Client

Cree el objeto Client mediante fromConnectionString usando estos parámetros:

• Cadena de conexión de IoT Hub
• Tipo de transporte

En este ejemplo, el objeto serviceClient se crea con el tipo de transporte Amqp.

var connectionString = '{IoT Hub connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

Apertura de la conexión de cliente

Llame al método Clientopen para abrir una conexión entre una aplicación e IoT Hub.

open se puede llamar a con o sin especificar una función de devolución de llamada a la que se llama cuando se completa la operación open.

En este ejemplo, el método open incluye una función opcional de devolución de llamada para abrir la conexión err. Si se produce un error de apertura, se devuelve un objeto error. Si la conexión se abre correctamente, se devuelve un valor de devolución de llamada null.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

Creación de un mensaje

El objeto message incluye el mensaje asincrónico de la nube al dispositivo. La funcionalidad del mensaje funciona de la misma manera a través de AMQP, MQTT y HTTP.

El objeto message admite varias propiedades, incluidas estas. Consulte las propiedades message para obtener una lista completa.

• ack: comentarios de entrega. Se describe en la sección siguiente.
• properties: mapa que contiene claves de cadena y valores para almacenar propiedades de mensaje personalizadas.
• messageId: se usa para poner en correlación la comunicación bidireccional.

Agregue el cuerpo del mensaje cuando se cree una instancia del objeto message. En este ejemplo, se agrega un mensaje 'Cloud to device message.'.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

Confirmación de entrega

Un programa de envío puede solicitar confirmaciones de entrega (o expiración) a IoT Hub para cada mensaje de la nube al dispositivo. Esta opción permite al programa de envío usar la lógica de información, reintento o compensación. Una descripción completa de las operaciones y propiedades de comentarios de mensajes se describen en Comentarios de mensajes.

Cada mensaje que va a recibir comentarios de mensajes debe incluir un valor para la propiedad de confirmación de entrega ack. La propiedad ack puede tener uno de estos valores:

• none (valor predeterminado): no se genera ningún mensaje de comentarios.

• sent: se recibe un mensaje de comentarios si el mensaje se ha completado.

• : se recibe un mensaje de comentarios si el mensaje ha expirado (o se ha alcanzado el número máximo de entregas) sin que el dispositivo lo complete.

• full: comentarios para los resultados enviados y no enviados.

En este ejemplo, la propiedad ack se establece en full, que solicita comentarios de entrega de mensajes enviados y no enviados para un mensaje.

message.ack = 'full';

Vinculación del receptor de comentarios del mensaje

La función de devolución de llamada del receptor de comentarios de mensajes está vinculada a Client mediante getFeedbackReceiver.

El receptor de comentarios del mensaje recibe dos argumentos:

• Objeto error (puede ser null)
• Objeto AmqpReceiver: emite eventos cuando el cliente recibe nuevos mensajes de comentarios.

Esta función de ejemplo recibe e imprime un mensaje de comentarios de entrega en la consola.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

Este código vincula la función de devolución de llamada de comentarios receiveFeedback al objeto Client de servicio mediante getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Definición de un controlador de resultados de finalización de mensajes

Se llama a la función de devolución de llamada de finalización de envío de mensajes después de enviar cada mensaje.

Esta función de ejemplo imprime los resultados de la operación send del mensaje en la consola. En este ejemplo, la función printResultFor se proporciona como parámetro a la función send descrita en la sección siguiente.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

Envío de un mensaje

Use la función send para enviar un mensaje asincrónico de la nube al dispositivo a la aplicación de dispositivo mediante IoT Hub.

send admite estos parámetros:

• deviceID: la identidad del dispositivo de destino.
• message: cuerpo del mensaje que se enviará al dispositivo.
• done: función opcional a la que se llamará cuando se complete la operación. Se llama a done con dos argumentos:
  • Objeto error (puede ser null).
  • Objeto de respuesta específico del transporte (útil para el registro o la depuración).

Este código llama a send para enviar un mensaje de la nube al dispositivo a la aplicación de dispositivo mediante IoT Hub. La función de devolución de llamada printResultFor definida en la sección anterior recibe la información de confirmación de entrega.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

En este ejemplo se muestra cómo enviar un mensaje a su dispositivo y controlar el mensaje de comentarios cuando el dispositivo reconozca el mensaje de la nube al dispositivo:

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

Ejemplo de envío de mensajes del SDK

send_c2d_message.js: envío de mensajes C2D a un dispositivo mediante IoT Hub.

Directiva de reconexión de la conexión

En este artículo no se muestra una directiva de reintentos de mensajes para la conexión del dispositivo a IoT Hub o la conexión de la aplicación externa a IoT Hub. En el código de producción, debe implementar directivas de reintentos de conexión como se describe en Administración de reconexión de dispositivos para crear aplicaciones resistentes.

Tiempo de retención de mensajes, reintentos y recuento máximo de entregas

Como se describe en Envío de mensajes de la nube al dispositivo desde IoT Hub, puede ver y configurar los valores predeterminados de los siguientes valores de mensaje mediante las opciones de configuración de IoT Hub del portal o la CLI de Azure. Estas opciones de configuración pueden afectar a la entrega y los comentarios de mensajes.

• TTL predeterminado (período de vida): la cantidad de tiempo que un mensaje está disponible para que un dispositivo lo consuma antes de que expire en IoT Hub.
• Tiempo de retención de comentarios: la cantidad de tiempo que IoT Hub conserva los comentarios de expiración o entrega de mensajes de la nube al dispositivo.
• Número de veces que IoT Hub intenta entregar un mensaje de la nube al dispositivo a un dispositivo.