Partilhar via

Enviar e receber mensagens da nuvem para o dispositivo

  • Artigo

O Hub IoT do Azure é um serviço totalmente gerenciado que permite comunicações bidirecionais, incluindo mensagens de nuvem para dispositivo (C2D) de back-ends de solução para milhões de dispositivos.

Este artigo descreve como usar os SDKs do Azure IoT para criar os seguintes tipos de aplicativos:

  • Aplicativos de dispositivo que recebem e manipulam mensagens da nuvem para o dispositivo de uma fila de mensagens do Hub IoT.

  • Aplicativos back-end que enviam mensagens da nuvem para o dispositivo para um único dispositivo por meio de uma fila de mensagens do Hub IoT.

Este artigo destina-se a complementar exemplos de SDK executáveis que são referenciados a partir deste artigo.

Nota

Os recursos descritos neste artigo estão disponíveis somente na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada certa do Hub IoT para sua solução.

Descrição geral

Para que um aplicativo de dispositivo receba mensagens da nuvem para o dispositivo, ele deve se conectar ao Hub IoT e, em seguida, configurar um manipulador de mensagens para processar mensagens de entrada. Os SDKs de dispositivo do Hub IoT do Azure fornecem classes e métodos que um dispositivo pode usar para receber e manipular mensagens do serviço. Este artigo descreve os principais elementos de qualquer aplicativo de dispositivo que recebe mensagens, incluindo:

  • Declarar um objeto cliente de dispositivo
  • Ligar a um Hub IoT
  • Recuperar mensagens da fila de mensagens do Hub IoT
  • Processar a mensagem e enviar uma confirmação de volta para o Hub IoT
  • Configurar uma política de repetição de mensagens de recebimento

Para que um aplicativo back-end envie mensagens da nuvem para o dispositivo, ele deve se conectar a um Hub IoT e enviar mensagens por meio de uma fila de mensagens do Hub IoT. Os SDKs de serviço do Hub IoT do Azure fornecem classes e métodos que um aplicativo pode usar para enviar mensagens para dispositivos. Este artigo descreve os principais elementos de qualquer aplicativo que envia mensagens para dispositivos, incluindo:

  • Declarar um objeto de cliente de serviço
  • Ligar a um Hub IoT
  • Crie e envie a mensagem
  • Receba feedback da entrega
  • Configurar uma política de repetição de mensagens de envio

Compreender a fila de mensagens

Para entender as mensagens de nuvem para dispositivo, é importante entender alguns fundamentos sobre como as filas de mensagens de dispositivo do Hub IoT funcionam.

As mensagens de nuvem para dispositivo enviadas de um aplicativo de back-end de solução para um dispositivo IoT são roteadas por meio do Hub IoT. Não há comunicação direta de mensagens ponto a ponto entre o aplicativo de back-end da solução e o dispositivo de destino. O Hub IoT coloca as mensagens recebidas em sua fila de mensagens, prontas para serem baixadas pelos dispositivos IoT de destino.

Para garantir a entrega de mensagens pelo menos uma vez, o hub IoT persiste mensagens da nuvem para o dispositivo em filas por dispositivo. Os dispositivos devem confirmar explicitamente a conclusão de uma mensagem antes que o Hub IoT remova a mensagem da fila. Essa abordagem garante resiliência contra falhas de conectividade e dispositivos.

Quando o Hub IoT coloca uma mensagem em uma fila de mensagens de dispositivo, ele define o estado da mensagem como Enfileirado. Quando um thread de dispositivo tira uma mensagem da fila, o Hub IoT bloqueia a mensagem definindo o estado da mensagem como Invisível. Esse estado impede que outros threads no dispositivo processem a mesma mensagem. Quando um thread de dispositivo conclui com êxito o processamento de uma mensagem, ele notifica o Hub IoT e, em seguida, o Hub IoT define o estado da mensagem como Concluído.

Um aplicativo de dispositivo que recebe e processa com êxito uma mensagem é dito para completar a mensagem. No entanto, se necessário, um dispositivo também pode:

  • Rejeite a mensagem, o que faz com que o Hub IoT a defina para o estado com letras mortas. Os dispositivos que se conectam pelo protocolo MQTT (Transporte de Telemetria de Enfileiramento de Mensagens) não podem rejeitar mensagens da nuvem para o dispositivo.
  • Abandone a mensagem, o que faz com que o Hub IoT coloque a mensagem de volta na fila, com o estado da mensagem definido como Enfileirado. Os dispositivos que se conectam pelo protocolo MQTT não podem abandonar mensagens de nuvem para dispositivo.

Para obter mais informações sobre o ciclo de vida de mensagens de nuvem para dispositivo e como o Hub IoT processa mensagens de nuvem para dispositivo, consulte Enviar mensagens de nuvem para dispositivo de um hub IoT.

Receba mensagens da nuvem para o dispositivo

Esta seção descreve como receber mensagens da nuvem para o dispositivo usando a classe DeviceClient no SDK do Azure IoT para .NET.

Há duas opções que um aplicativo cliente de dispositivo pode usar para receber mensagens:

  • Sondagem: o aplicativo do dispositivo verifica se há novas mensagens do Hub IoT usando um loop de código (por exemplo, um while ou for loop). O loop é executado continuamente, verificando se há mensagens.
  • Retorno de chamada: o aplicativo de dispositivo configura um método de manipulador de mensagens assíncrono que é chamado imediatamente quando uma mensagem chega.

Declarar um objeto DeviceClient

DeviceClient inclui métodos e propriedades necessários para receber mensagens do Hub IoT.

Por exemplo:

static DeviceClient deviceClient;

Forneça os parâmetros de conexão

Forneça a cadeia de conexão primária do Hub IoT e a ID do dispositivo para DeviceClient usar o método CreateFromConnectionString . Além da cadeia de conexão primária necessária do Hub IoT, o CreateFromConnectionString método pode ser sobrecarregado para incluir estes parâmetros opcionais :

  • transportType - O protocolo de transporte: variações de HTTP versão 1, AMQP ou MQTT. AMQP é a predefinição. Para ver todos os valores disponíveis, consulte TransportType Enum.
  • transportSettings - Interface usada para definir várias configurações específicas de transporte para DeviceClient e ModuleClient. Para obter mais informações, consulte ITransportSettings Interface.
  • ClientOptions - Opções que permitem a configuração do dispositivo ou instância do cliente do módulo durante a inicialização.

Este exemplo chama CreateFromConnectionString para definir as configurações de conexão do hub IoT e do ID do DeviceClient dispositivo.

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

Consultas

A sondagem usa ReceiveAsync para verificar se há mensagens.

Um convite à apresentação de propostas pode ReceiveAsync assumir as seguintes formas:

  • ReceiveAsync() - Aguarde o período de tempo limite padrão para uma mensagem antes de continuar.
  • ReceiveAsync (Timespan) - Receba uma mensagem da fila de dispositivos usando um tempo limite específico.
  • ReceiveAsync (CancellationToken) - Receba uma mensagem da fila do dispositivo usando um token de cancelamento. Ao usar um token de cancelamento, o período de tempo limite padrão não é usado.

Ao usar um tipo de transporte HTTP 1 em vez de MQTT ou AMQP, o ReceiveAsync método retorna imediatamente. O padrão suportado para mensagens da nuvem para o dispositivo com HTTP 1 são dispositivos conectados intermitentemente que verificam mensagens com pouca frequência (um mínimo de cada 25 minutos). Emitir mais HTTP 1 gera resultados no Hub IoT limitando as solicitações. Para obter mais informações sobre as diferenças entre o suporte a MQTT, AMQP e HTTP 1, consulte Orientação de comunicações entre a nuvem e o dispositivo e Escolha um protocolo de comunicação.

Método CompleteAsync

Depois que o dispositivo recebe uma mensagem, o aplicativo de dispositivo chama o método CompleteAsync para notificar o Hub IoT de que a mensagem foi processada com êxito e que a mensagem pode ser removida com segurança da fila de dispositivos do Hub IoT. O dispositivo deve chamar esse método quando seu processamento for concluído com êxito, independentemente do protocolo de transporte que estiver usando.

Abandono, rejeição ou tempo limite da mensagem

Com os protocolos AMQP e HTTP versão 1, mas não o protocolo MQTT, o dispositivo também pode:

  • Abandone uma mensagem chamando AbandonAsync. Isso resulta em Hub IoT retendo a mensagem na fila de dispositivos para consumo futuro.
  • Rejeite uma mensagem chamando RejectAsync. Isso remove permanentemente a mensagem da fila do dispositivo.

Se acontecer algo que impeça o dispositivo de concluir, abandonar ou rejeitar a mensagem, o Hub IoT irá, após um período de tempo limite fixo, enfileirar a mensagem para entrega novamente. Por esse motivo, a lógica de processamento de mensagens no aplicativo do dispositivo deve ser idempotente, para que receber a mesma mensagem várias vezes produza o mesmo resultado.

Para obter mais informações sobre o ciclo de vida de mensagens de nuvem para dispositivo e como o Hub IoT processa mensagens de nuvem para dispositivo, consulte Enviar mensagens de nuvem para dispositivo de um hub IoT.

Circuito de votação

Usando sondagem, um aplicativo usa um loop de código que chama o ReceiveAsync método repetidamente para verificar se há novas mensagens até ser interrompido.

Se estiver usando ReceiveAsync com um valor de tempo limite ou o tempo limite padrão, no loop cada chamada aguarda ReceiveAsync o período de tempo limite especificado. Se ReceiveAsync o tempo limite expirar, um null valor será retornado e o loop continuará.

Quando uma mensagem é recebida, um objeto Task é retornado por ReceiveAsync que deve ser passado para CompleteAsync. Uma chamada para CompleteAsync notificar o Hub IoT para excluir a mensagem especificada da fila de mensagens com base no Task parâmetro.

Neste exemplo, o loop chama ReceiveAsync até que uma mensagem seja recebida ou o loop de sondagem seja interrompido.

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 ();
}

Chamada de Retorno

Para receber mensagens de retorno de chamada da nuvem para o dispositivo no aplicativo do dispositivo, o aplicativo deve se conectar ao Hub IoT e configurar um ouvinte de retorno de chamada para processar mensagens de entrada. As mensagens de entrada no dispositivo são recebidas da fila de mensagens do Hub IoT.

Usando retorno de chamada, o aplicativo de dispositivo configura um método de manipulador de mensagens usando SetReceiveMessageHandlerAsync. O manipulador de mensagens é chamado e, em seguida, uma mensagem é recebida. Criar um método de retorno de chamada para receber mensagens elimina a necessidade de pesquisar continuamente as mensagens recebidas.

O retorno de chamada está disponível somente usando estes protocolos:

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

A Http1 opção de protocolo não suporta retornos de chamada, uma vez que os métodos SDK precisariam pesquisar mensagens recebidas de qualquer maneira, o que derrota o princípio de retorno de chamada.

Neste exemplo, SetReceiveMessageHandlerAsync configura um método de manipulador de retorno de chamada chamado OnC2dMessageReceivedAsync, que é chamado sempre que uma mensagem é recebida.

// 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.");

Política de repetição de mensagens de recebimento

A política de repetição de mensagem do cliente de dispositivo pode ser definida usando DeviceClient.SetRetryPolicy.

O tempo limite de repetição da mensagem é armazenado na propriedade DeviceClient.OperationTimeoutInMilliseconds .

Exemplo de mensagem de recebimento do SDK

O SDK .NET/C# inclui um exemplo de Recebimento de Mensagem que inclui os métodos de mensagem de recebimento descritos nesta seção.

Enviar mensagens da cloud para o dispositivo

Esta seção descreve o código essencial para enviar uma mensagem de um aplicativo de back-end de solução para um dispositivo IoT usando a classe ServiceClient no SDK do Azure IoT para .NET. Como discutido anteriormente, um aplicativo de back-end de solução se conecta a um Hub IoT e as mensagens são enviadas para o Hub IoT codificadas com um dispositivo de destino. O Hub IoT armazena mensagens de entrada em sua fila de mensagens e as mensagens são entregues da fila de mensagens do Hub IoT para o dispositivo de destino.

Um aplicativo de back-end de solução também pode solicitar e receber feedback de entrega para uma mensagem enviada ao Hub IoT destinada à entrega do dispositivo por meio da fila de mensagens.

Declarar um objeto ServiceClient

ServiceClient inclui métodos e propriedades necessárias para enviar mensagens de um aplicativo por meio do Hub IoT para um dispositivo.

static ServiceClient serviceClient;

Fornecer a cadeia de conexão

Forneça a cadeia de conexão primária do Hub IoT para ServiceClient usar o método CreateFromConnectionString . Além da cadeia de conexão primária necessária do Hub IoT, o CreateFromConnectionString método pode ser sobrecarregado para incluir estes parâmetros opcionais :

  • transportType - Amqp ou Amqp_WebSocket_Only.
  • transportSettings - As configurações de proxy AMQP e HTTP para o Service Client.
  • ServiceClientOptions - Opções que permitem a configuração da instância do cliente de serviço durante a inicialização. Para obter mais informações, consulte ServiceClientOptions.

Este exemplo cria o ServiceClient objeto usando a cadeia de conexão do Hub IoT.

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

Enviar uma mensagem assíncrona da nuvem para o dispositivo

Use sendAsync para enviar uma mensagem assíncrona de um aplicativo através da nuvem (Hub IoT) para o dispositivo. A chamada é feita usando o protocolo AMQP.

sendAsync utiliza estes parâmetros:

  • deviceID - O identificador de string do dispositivo alvo.
  • message - A mensagem nuvem-para-dispositivo. A mensagem é do tipo Mensagem e pode ser formatada de acordo.
  • timeout - Um valor de tempo limite opcional . O padrão é um minuto se não especificado.

Este exemplo envia uma mensagem de teste para o dispositivo de destino com o valor de tempo limite 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);

Receba feedback da entrega

Um programa de envio pode solicitar confirmações de entrega (ou expiração) do Hub IoT para cada mensagem da nuvem para o dispositivo. Essa opção permite que o programa de envio use a lógica informar, repetir ou compensar. Uma descrição completa das operações e propriedades de feedback de mensagens é descrita em Comentários de mensagens.

Para receber comentários sobre a entrega de mensagens:

  • Criar o feedbackReceiver objeto
  • Enviar mensagens usando o Ack parâmetro
  • Aguarde para receber comentários

Criar o objeto feedbackReceiver

Chame GetFeedbackReceiver para criar um objeto FeedbackReceiver . FeedbackReceiver Contém métodos que os serviços podem usar para executar operações de recebimento de feedback.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Enviar mensagens usando o parâmetro Ack

Cada mensagem deve incluir um valor para a propriedade Ack de confirmação de entrega para receber feedback de entrega. A Ack propriedade pode ser um destes valores:

  • Nenhum (padrão): Nenhuma mensagem de feedback é gerada.

  • Positive: Receba uma mensagem de feedback se a mensagem foi concluída.

  • Negative: Receba uma mensagem de feedback se a mensagem expirou (ou a contagem máxima de entrega foi atingida) sem ser concluída pelo dispositivo.

  • Full: feedback para ambos e Positive Negative resultados.

Neste exemplo, a Ack propriedade é definida como Full, solicitando feedback de entrega de mensagens positivas ou negativas para uma mensagem.

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

Aguarde para receber comentários

Defina um CancellationTokenarquivo . Em seguida, em um loop, chame ReceiveAsync repetidamente, verificando se há mensagens de feedback de entrega. Cada chamada aguarda ReceiveAsync o período de tempo limite definido para o ServiceClient objeto.

  • Se um ReceiveAsync tempo limite expirar sem nenhuma mensagem recebida, ReceiveAsync retornará null e o loop continuará.
  • Se uma mensagem de feedback for recebida, um objeto Task será retornado por ReceiveAsync que deve ser passado para CompleteAsync junto com o token de cancelamento. Uma chamada para CompleteAsync excluir a mensagem enviada especificada da fila de mensagens com base no Task parâmetro.
  • Se necessário, o código de recebimento pode chamar AbandonAsync para colocar uma mensagem de envio de volta na fila.
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;

Este exemplo mostra um método que inclui essas etapas.

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);
      }
   }

Observe que esse padrão de recebimento de comentários é semelhante ao padrão usado para receber mensagens da nuvem para o dispositivo no aplicativo do dispositivo.

Reconexão do cliente de serviço

Ao encontrar uma exceção, o cliente de serviço retransmite essas informações para o aplicativo de chamada. Nesse ponto, é recomendável que você inspecione os detalhes da exceção e tome as medidas necessárias.

Por exemplo:

  • Se for uma exceção de rede, você pode tentar novamente a operação.
  • Se for uma exceção de segurança (exceção não autorizada), inspecione suas credenciais e verifique se elas estão atualizadas.
  • Se for uma exceção de limitação/cota excedida, monitore e/ou modifique a frequência de envio de solicitações ou atualize sua unidade de escala de instância de hub. Consulte Cotas e limitação do Hub IoT para obter detalhes.

Enviar política de repetição de mensagem

A ServiceClient política de repetição de mensagem pode ser definida usando ServiceClient.SetRetryPolicy.

Exemplo de mensagem de envio do SDK

O SDK .NET/C# inclui um exemplo de cliente de serviço que inclui os métodos de mensagem de envio descritos nesta seção.

Receba mensagens da nuvem para o dispositivo

Esta seção descreve como receber mensagens da nuvem para o dispositivo usando a classe DeviceClient do SDK do Azure IoT para Java.

Para que um aplicativo de dispositivo baseado em Java receba mensagens da nuvem para o dispositivo, ele deve se conectar ao Hub IoT e, em seguida, configurar um ouvinte de retorno de chamada e um manipulador de mensagens para processar mensagens de entrada do Hub IoT. O aplicativo de dispositivo também deve ser capaz de detetar e lidar com desconexões caso a conexão de mensagem do dispositivo para o Hub IoT seja interrompida.

Importar bibliotecas do SDK Java do Azure IoT

O código mencionado neste artigo usa essas bibliotecas 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;

Declarar um objeto DeviceClient

A instanciação do objeto DeviceClient requer estes parâmetros:

  • connString - A cadeia de conexão do dispositivo IoT. A cadeia de conexão é um conjunto de pares chave-valor que são separados por ';', com as chaves e valores separados por '='. Ele deve conter valores para estas chaves: HostName, DeviceId, and SharedAccessKey.
  • Protocolo de transporte - A DeviceClient conexão pode usar um dos seguintes protocolos de transporte IoTHubClientProtocol. AMQP é o mais versátil, permite verificar mensagens com frequência e permite a rejeição e cancelamento de mensagens. O MQTT não suporta métodos de rejeição ou abandono de mensagens:
    • AMQPS
    • AMQPS_WS
    • HTTPS
    • MQTT
    • MQTT_WS

Por exemplo:

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

Definir o método de retorno de chamada de mensagem

Use o método setMessageCallback para definir um método de manipulador de mensagens que é notificado quando uma mensagem é recebida do Hub IoT.

setMessageCallback inclui estes parâmetros:

  • callback - O nome do método de retorno de chamada. Pode ser null.
  • context - Um contexto opcional do tipo object. Use null se não especificado.

Neste exemplo, um callback método nomeado MessageCallback sem parâmetro de contexto é passado para setMessageCallback.

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

Criar um manipulador de retorno de chamada de mensagem

Um manipulador de mensagens de retorno de chamada recebe e processa uma mensagem de entrada passada da fila de mensagens do Hub IoT.

Neste exemplo, o manipulador de mensagens processa uma mensagem de entrada e retorna IotHubMessageResult.COMPLETE. Um IotHubMessageResult.COMPLETE valor de retorno notifica o Hub IoT de que a mensagem foi processada com êxito e que a mensagem pode ser removida com segurança da fila de dispositivos. O dispositivo deve retornar IotHubMessageResult.COMPLETE quando seu processamento for concluído com êxito, notificando o Hub IoT de que a mensagem deve ser removida da fila de mensagens, independentemente do protocolo que está usando.

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

Opções de abandono e rejeição de mensagens

Embora o grande número de mensagens recebidas em um dispositivo deva ser recebido com sucesso e resultar em IotHubMessageResult.COMPLETE, pode ser necessário abandonar ou rejeitar uma mensagem.

  • Com AMQP e HTTPS, mas não MQTT, um aplicativo pode:
    • IotHubMessageResult.ABANDON a mensagem. O hub IoT o recoloca na fila e o envia novamente mais tarde.
    • IotHubMessageResult.REJECT a mensagem. O hub IoT não coloca a mensagem na fila novamente e a remove permanentemente da fila de mensagens.
  • Clientes que usam MQTT ou MQTT_WS não podem ABANDON ou REJECT mensagens.

Se acontecer algo que impeça o dispositivo de concluir, abandonar ou rejeitar a mensagem, o Hub IoT irá, após um período de tempo limite fixo, enfileirar a mensagem para entrega novamente. Por esse motivo, a lógica de processamento de mensagens no aplicativo do dispositivo deve ser idempotente, para que receber a mesma mensagem várias vezes produza o mesmo resultado.

Para obter mais informações sobre o ciclo de vida de mensagens de nuvem para dispositivo e como o Hub IoT processa mensagens de nuvem para dispositivo, consulte Enviar mensagens de nuvem para dispositivo de um hub IoT.

Nota

Se você usar HTTPS em vez de MQTT ou AMQP como transporte, a instância DeviceClient verificará mensagens do Hub IoT com pouca frequência (no mínimo a cada 25 minutos). Para obter mais informações sobre as diferenças entre o suporte a MQTT, AMQP e HTTPS, consulte Orientação de comunicações da nuvem para o dispositivo e Escolha um protocolo de comunicação.

Criar o método de retorno de chamada do estado da mensagem

Um aplicativo pode usar registerConnectionStatusChangeCallback para registrar um método de retorno de chamada a ser executado quando o status da conexão do dispositivo muda. Desta forma, o aplicativo pode detetar uma conexão de mensagens derrubada e tentar se reconectar.

Neste exemplo, IotHubConnectionStatusChangeCallbackLogger é registrado como o método de retorno de chamada de alteração de status da conexão.

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

O retorno de chamada é disparado e passado um ConnectionStatusChangeContext objeto.

Ligue connectionStatusChangeContext.getNewStatus() para obter o estado atual da conexão.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

O estado da conexão retornado pode ser um destes valores:

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

Ligue connectionStatusChangeContext.getNewStatusReason() para obter o motivo da alteração do status da conexão.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Ligue connectionStatusChangeContext.getCause() para encontrar o motivo da alteração do status da conexão. getCause() pode regressar null se não houver informação disponível.

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

Consulte o exemplo HandleMessages listado na seção Exemplo de mensagem de recebimento do SDK deste artigo para obter um exemplo completo mostrando como extrair a alteração de status, o método de retorno de chamada, o status da conexão, o status da alteração, o motivo pelo qual o status do dispositivo foi alterado e o contexto.

Abra a conexão entre o dispositivo e o Hub IoT

Use open para criar uma conexão entre o dispositivo e o Hub IoT. O dispositivo agora pode enviar e receber mensagens de forma assíncrona de e para um Hub IoT. Se o cliente já estiver aberto, o método não fará nada.

client.open(true);

Exemplo de mensagem de recebimento do SDK

HandleMessages: um aplicativo de dispositivo de exemplo incluído no SDK do Microsoft Azure IoT para Java, que se conecta ao seu hub IoT e recebe mensagens da nuvem para o dispositivo.

Enviar mensagens da cloud para o dispositivo

Esta seção descreve como enviar uma mensagem da nuvem para o dispositivo usando a classe ServiceClient do SDK do Azure IoT para Java. Um aplicativo de back-end de solução se conecta a um Hub IoT e as mensagens são enviadas para o Hub IoT codificadas com um dispositivo de destino. O Hub IoT armazena mensagens de entrada em sua fila de mensagens e as mensagens são entregues da fila de mensagens do Hub IoT para o dispositivo de destino.

Um aplicativo de back-end de solução também pode solicitar e receber feedback de entrega para uma mensagem enviada ao Hub IoT destinada à entrega do dispositivo por meio da fila de mensagens.

Adicionar a instrução de dependência

Adicione a dependência para usar o pacote iothub-java-service-client em seu aplicativo para se comunicar com seu serviço de hub IoT:

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

Adicionar instruções de importação

Adicione essas instruções de importação para usar o SDK Java do Azure IoT e o manipulador de exceções.

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

Definir o protocolo de conexão

Use IotHubServiceClientProtocol para definir o protocolo de camada de aplicativo usado pelo cliente de serviço para se comunicar com um Hub IoT.

IotHubServiceClientProtocol só aceita o AMQPS ou AMQPS_WS enum.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Criar o objeto ServiceClient

Crie o objeto ServiceClient , fornecendo a cadeia de conexão e o protocolo do Hub IoT.

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

Abra a conexão entre o aplicativo e o Hub IoT

abra a conexão de remetente AMQP. Esse método cria a conexão entre o aplicativo e o Hub IoT.

serviceClient.open();

Abrir um recetor de feedback para feedback de entrega de mensagens

Você pode usar um FeedbackReceiver para receber mensagens enviadas para comentários do Hub IoT. A FeedbackReceiver é um recetor especializado cujo Receive método retorna um FeedbackBatch em vez de um Message.

Neste exemplo, o FeedbackReceiver objeto é criado e a open() instrução é chamada para aguardar feedback.

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

Adicionar propriedades da mensagem

Opcionalmente, você pode usar setProperties para adicionar propriedades de mensagem. Essas propriedades são incluídas na mensagem enviada para o dispositivo e podem ser extraídas pelo aplicativo do dispositivo após o recebimento.

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

Criar e enviar uma mensagem assíncrona

O objeto Message armazena a mensagem a ser enviada. Neste exemplo, uma mensagem "Cloud to device" é entregue.

Use setDeliveryAcknowledgement para solicitar a confirmação da fila de mensagens entregue/não entregue ao Hub IoT. Neste exemplo, a confirmação solicitada é Full, entregue ou não entregue.

Use SendAsync para enviar uma mensagem assíncrona do cliente para o dispositivo. Como alternativa, você pode usar o método (não assíncrono Send ), mas essa função é sincronizada internamente para que apenas uma operação de envio seja permitida de cada vez. A mensagem é entregue do aplicativo para o Hub IoT. O Hub IoT coloca a mensagem na fila de mensagens, pronta para ser entregue ao dispositivo de destino.

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

Receber feedback sobre a entrega de mensagens

Depois que uma mensagem é enviada do aplicativo, o aplicativo pode chamar o recebimento com ou sem um valor de tempo limite. Se um valor de tempo limite não for fornecido, o tempo limite padrão será usado. Isso passa de volta um objeto FeedbackBatch que contém propriedades de feedback de entrega de mensagens que podem ser examinadas.

Este exemplo cria o FeedbackBatch recetor e chama getEnqueuedTimeUtc, imprimindo o tempo enfileirado da mensagem.

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

SDK enviar exemplos de mensagens

  • Exemplo de cliente de serviço - Exemplo de mensagem de envio, #1.

  • Exemplo de cliente de serviço - Exemplo de mensagem de envio, #2.

Instalar a biblioteca do SDK do Azure IoT

Instale a biblioteca do SDK azure-iot-device em sua máquina de desenvolvimento antes de chamar qualquer código relacionado:

pip install azure-iot-device

Há duas classes Python SDK que são usadas para enviar mensagens de e para dispositivos IoT. Os métodos de manipulação de mensagens dessas classes são descritos nas seções desta página.

  • A classe IoTHubDeviceClient inclui métodos para criar uma conexão síncrona de um dispositivo para um Hub IoT do Azure e receber mensagens do Hub IoT.

  • A classe IoTHubRegistryManager inclui APIs para operações do Gerenciador do Registro do Hub IoT. Neste artigo, os métodos dessa classe mostram como se conectar ao Hub IoT e enviar uma mensagem para um dispositivo.

Receba mensagens da nuvem para o dispositivo

Esta seção descreve como receber mensagens da nuvem para o dispositivo usando a classe IoTHubDeviceClient do SDK do Azure IoT para Python.

Para que um aplicativo de dispositivo baseado em Python receba mensagens da nuvem para o dispositivo, ele deve se conectar ao Hub IoT e, em seguida, configurar um manipulador de mensagens de retorno de chamada para processar mensagens de entrada do Hub IoT.

Importar o objeto IoTHubDeviceClient

Adicione uma linha de código para importar as IoTHubDeviceClient funções do SDK azure.iot.device.

from azure.iot.device import IoTHubDeviceClient

Conectar o cliente do dispositivo

Instancie o IoTHubDeviceClient, passando uma cadeia de conexão do Hub IoT para create_from_connection_string. Isso cria uma conexão do dispositivo com o Hub IoT.

Como alternativa, você pode se conectar IoTHubDeviceClienta um dispositivo usando um destes métodos:

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

Lidar com a reconexão

IoTHubDeviceClient tentará, por padrão, restabelecer uma conexão descartada. O comportamento de reconexão é regido IoTHubDeviceClient pelos connection_retry e connection_retry_interval parâmetros.

Criar um manipulador de mensagens

Crie a função de manipulador de mensagens para processar mensagens recebidas para o dispositivo.

Neste exemplo, message_handler é chamado quando uma mensagem é recebida. As propriedades da mensagem (.items) são impressas no console usando um loop.

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))

Atribuir o manipulador de mensagens

Use o método on_message_received para atribuir o método manipulador de mensagens ao IoTHubDeviceClient objeto.

Neste exemplo, um método de manipulador de mensagens chamado message_handler é anexado ao IoTHubDeviceClient client objeto. O client objeto aguarda para receber uma mensagem de nuvem para dispositivo de um Hub IoT. Esse código aguarda até 300 segundos (5 minutos) por uma mensagem ou sai se uma tecla do teclado for pressionada.

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()

Exemplo de mensagem de recebimento do SDK

Receber mensagem - Receba mensagens C2D (Cloud-to-Device) enviadas do Hub IoT do Azure para um dispositivo.

Enviar mensagens da cloud para o dispositivo

Esta seção descreve como enviar uma mensagem da nuvem para o dispositivo usando a classe IoTHubRegistryManager do SDK do Azure IoT para Python. Um aplicativo de back-end de solução se conecta a um Hub IoT e as mensagens são enviadas para o Hub IoT codificadas com um dispositivo de destino. O Hub IoT armazena mensagens de entrada em sua fila de mensagens e as mensagens são entregues da fila de mensagens do Hub IoT para o dispositivo de destino.

Importar o objeto IoTHubRegistryManager

Adicione a seguinte import instrução. O IoTHubRegistryManager inclui APIs para operações do Gerenciador do Registro do Hub IoT.

from azure.iot.hub import IoTHubRegistryManager

Conectar o gerenciador de registro do Hub IoT

Instancie o objeto IoTHubRegistryManager que se conecta a um hub IoT, passando uma cadeia de conexão do Hub IoT para from_connection_string.

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

Criar e enviar uma mensagem

Use send_c2d_message para enviar uma mensagem através da nuvem (Hub IoT) para o dispositivo.

send_c2d_message utiliza estes parâmetros:

  • deviceID - O identificador de string do dispositivo alvo.
  • message - A mensagem nuvem-para-dispositivo. A mensagem é do tipo str (string).
  • properties - Uma coleção opcional de propriedades do tipo dict. As propriedades podem conter propriedades do aplicativo e propriedades do sistema. O valor predefinido é {}.

Este exemplo envia uma mensagem de teste para o 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)

Exemplo de mensagem de envio do SDK

send_message.py - Demonstra como enviar uma mensagem da nuvem para o dispositivo.

Instalar os pacotes de mensagens Node.js

Execute estes comandos para instalar os pacotes azure-iot-device e azure-iothub em sua máquina de desenvolvimento:

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

O pacote azure-iot-device contém objetos que fazem interface com dispositivos IoT. Este artigo descreve o Client código de classe que recebe mensagens do Hub IoT.

O pacote azure-iothub contém objetos que fazem interface com o Hub IoT. Este artigo descreve Client o código de classe que envia uma mensagem de um aplicativo para um dispositivo via Hub IoT.

Receber mensagens no aplicativo do dispositivo

Esta seção descreve como receber mensagens da nuvem para o dispositivo usando o pacote azure-iot-device no SDK do Azure IoT para Node.js.

Para que um aplicativo de dispositivo baseado em Node.js receba mensagens da nuvem para o dispositivo, ele deve se conectar ao Hub IoT e, em seguida, configurar um ouvinte de retorno de chamada e um manipulador de mensagens para processar mensagens de entrada do Hub IoT. O aplicativo de dispositivo também deve ser capaz de detetar e lidar com desconexões caso a conexão de mensagem do dispositivo para o Hub IoT seja interrompida.

Criar um módulo cliente

A partir do azure-iot-device pacote, crie um Client usando a classe Client . A Client classe contém métodos que um dispositivo pode usar para receber e enviar para o Hub IoT.

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

Escolha um protocolo de transporte

O Client objeto suporta estes protocolos:

  • Amqp
  • Http - Ao usar Httpo , a Client instância verifica mensagens do Hub IoT com pouca frequência (no mínimo a cada 25 minutos).
  • Mqtt
  • MqttWs
  • AmqpWs

Para obter mais informações sobre as diferenças entre o suporte a MQTT, AMQP e HTTPS, consulte Orientação de comunicações da nuvem para o dispositivo e Escolha um protocolo de comunicação.

Este exemplo atribui o protocolo AMQP a uma Protocol variável. Essa variável de protocolo é passada para o Client.fromConnectionString método na seção Adicionar a cadeia de conexão deste artigo.

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

Recursos de conclusão, rejeição e abandono de mensagens

Os métodos de conclusão, rejeição e abandono de mensagens podem ser usados dependendo do protocolo escolhido.

AMQP e HTTP

Os transportes AMQP e HTTP podem concluir, rejeitar ou abandonar uma mensagem:

  • Concluído - Para concluir uma mensagem, o serviço que enviou a mensagem da nuvem para o dispositivo é notificado de que a mensagem foi recebida. O Hub IoT remove a mensagem da fila de mensagens. O método assume a forma de client.complete(message, callback function).
  • Rejeitar - Para rejeitar uma mensagem, o serviço que enviou a mensagem da nuvem para o dispositivo é notificado de que a mensagem não é processada pelo dispositivo. O Hub IoT remove permanentemente a mensagem da fila de dispositivos. O método assume a forma de client.reject(message, callback function).
  • Abandonar - Para abandonar uma mensagem, o Hub IoT tenta imediatamente reenviá-la. O Hub IoT retém a mensagem na fila de dispositivos para consumo futuro. O método assume a forma de client.abandon(message, callback function).
MQTT

O MQTT não suporta funções de mensagem completa, rejeitada ou abandonada. Em vez disso, o MQTT aceita uma mensagem por padrão e a mensagem é removida da fila de mensagens do Hub IoT.

Tentativas de reentrega

Se acontecer algo que impeça o dispositivo de concluir, abandonar ou rejeitar a mensagem, o Hub IoT irá, após um período de tempo limite fixo, enfileirar a mensagem para entrega novamente. Por esse motivo, a lógica de processamento de mensagens no aplicativo do dispositivo deve ser idempotente, para que receber a mesma mensagem várias vezes produza o mesmo resultado.

Adicionar a cadeia de caracteres e o protocolo de transporte do Hub IoT

Chame fromConnectionString para estabelecer uma conexão de dispositivo para hub IoT usando estes parâmetros:

  • connStr - Uma cadeia de conexão que encapsula permissões de "conexão de dispositivo" para um hub IoT. A cadeia de conexão contém Hostname, Device ID & Shared Access Key neste formato: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>"
  • transportCtor - O protocolo de transporte.
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Criar um manipulador de mensagens de entrada

O manipulador de mensagens é chamado para cada mensagem de entrada.

Depois que uma mensagem for recebida com êxito, se estiver usando o transporte AMQP ou HTTP, chame o método para informar ao client.complete Hub IoT que a mensagem pode ser removida da fila de mensagens.

Por exemplo, esse manipulador de mensagens imprime o ID e o corpo da mensagem no console e, em seguida, chama client.complete para notificar o Hub IoT de que processou a mensagem e que ela pode ser removida com segurança da fila de dispositivos. A chamada para complete não é necessária se você estiver usando o transporte MQTT e pode ser omitida. Uma chamada para é necessária paracomplete o transporte AMQP ou HTTPS.

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

Criar um manipulador de desconexão de conexão

O manipulador de desconexão é chamado quando a conexão é desconectada. Um manipulador de desconexão é útil para implementar o código de reconexão.

Este exemplo captura e exibe a mensagem de erro de desconexão no console.

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

Adicionar ouvintes de eventos

Você pode especificar esses ouvintes de eventos usando o método .on .

  • Manipulador de conexão
  • Manipulador de erros
  • Manipulador de desconexão
  • Manipulador de mensagens

Este exemplo inclui os manipuladores de mensagem e desconexão definidos anteriormente.

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

Abra a conexão com o Hub IoT

Use o método open para abrir uma conexão entre um dispositivo IoT e o Hub IoT. Use .catch(err) para capturar um erro e chamar o código do manipulador.

Por exemplo:

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

Exemplo de mensagem de recebimento do SDK

simple_sample_device - Um aplicativo de dispositivo que se conecta ao seu hub IoT e recebe mensagens da nuvem para o dispositivo.

Enviar mensagens da cloud para o dispositivo

Esta seção descreve como enviar uma mensagem da nuvem para o dispositivo usando o pacote azure-iothub do SDK do Azure IoT para Node.js. Como discutido anteriormente, um aplicativo de back-end de solução se conecta a um Hub IoT e as mensagens são enviadas para o Hub IoT codificadas com um dispositivo de destino. O Hub IoT armazena mensagens de entrada em sua fila de mensagens e as mensagens são entregues da fila de mensagens do Hub IoT para o dispositivo de destino.

Um aplicativo de back-end de solução também pode solicitar e receber feedback de entrega para uma mensagem enviada ao Hub IoT destinada à entrega do dispositivo por meio da fila de mensagens.

Carregue o cliente e os módulos de mensagem

Declare um Client objeto usando a Client azure-iothub classe do pacote.

Declare um Message objeto usando a Message azure-iot-common classe do pacote.

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

Criar o objeto Client

Crie o cliente usando fromConnectionString usando estes parâmetros:

  • Cadeia de conexão do Hub IoT
  • Tipo de transporte

Neste exemplo, o serviceClient objeto é criado com o Amqp tipo de transporte.

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

Abra a conexão do cliente

Chame o método open para abrir uma conexão entre um aplicativo e o Client Hub IoT.

open pode ser chamado com ou sem especificar uma função de retorno de chamada que é chamada quando a open operação é concluída.

Neste exemplo, o open método inclui uma função opcional err de retorno de chamada de conexão aberta. Se ocorrer um erro aberto, um objeto de erro será retornado. Se a conexão aberta for bem-sucedida, um valor de retorno de null chamada será retornado.

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

Criar uma mensagem

O objeto message inclui a mensagem assíncrona da nuvem para o dispositivo. A funcionalidade de mensagem funciona da mesma forma em AMQP, MQTT e HTTP.

O objeto message oferece suporte a várias propriedades, incluindo essas propriedades. Consulte as propriedades da mensagem para obter uma lista completa.

  • ack - Feedback da entrega. Descrito na próxima seção.
  • properties - Um mapa contendo chaves de cadeia de caracteres e valores para armazenar propriedades de mensagens personalizadas.
  • messageId - Usado para correlacionar a comunicação bidirecional.

Adicione o corpo da mensagem quando o objeto de mensagem for instanciado. Neste exemplo, uma 'Cloud to device message.' mensagem é adicionada.

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

Aviso de entrega

Um programa de envio pode solicitar confirmações de entrega (ou expiração) do Hub IoT para cada mensagem da nuvem para o dispositivo. Essa opção permite que o programa de envio use a lógica informar, repetir ou compensar. Uma descrição completa das operações e propriedades de feedback de mensagens é descrita em Comentários de mensagens.

Cada mensagem que deve receber feedback da mensagem deve incluir um valor para a propriedade ack de confirmação de entrega. A ack propriedade pode ser um destes valores:

  • Nenhum (padrão): Nenhuma mensagem de feedback é gerada.

  • sent: Receba uma mensagem de feedback se a mensagem foi concluída.

  • : Receba uma mensagem de feedback se a mensagem expirou (ou a contagem máxima de entrega foi atingida) sem ser concluída pelo dispositivo.

  • full: feedback para os resultados enviados e não enviados.

Neste exemplo, a ack propriedade é definida como full, solicitando comentários de entrega de mensagens enviadas e não enviadas para uma mensagem.

message.ack = 'full';

A função de retorno de chamada do recetor de feedback de mensagem está vinculada ao Client uso de getFeedbackReceiver.

O recetor de feedback da mensagem recebe dois argumentos:

  • Objeto de erro (pode ser nulo)
  • Objeto AmqpReceiver - Emite eventos quando novas mensagens de feedback são recebidas pelo cliente.

Esta função de exemplo recebe e imprime uma mensagem de feedback de entrega para o console.

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

Esse código vincula a função de retorno de chamada de receiveFeedback feedback ao objeto de serviço Client usando getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Definir um manipulador de resultados de conclusão de mensagem

A função de retorno de chamada de conclusão de envio de mensagem é chamada depois que cada mensagem é enviada.

Esta função de exemplo imprime os resultados da operação de mensagem send no console. Neste exemplo, a printResultFor função é fornecida como um parâmetro para a send função descrita na próxima seção.

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);
  };
}

Enviar uma mensagem

Use a função send para enviar uma mensagem assíncrona da nuvem para o dispositivo para o aplicativo do dispositivo por meio do Hub IoT.

send suporta estes parâmetros:

  • deviceID - O ID do dispositivo de destino.
  • message - O corpo da mensagem a ser enviada para o dispositivo.
  • done - A função opcional a ser chamada quando a operação for concluída. Done é chamado com dois argumentos:
    • Objeto de erro (pode ser nulo).
    • objeto de resposta específico de transporte útil para registro em log ou depuração.

Esse código chama send para enviar uma mensagem da nuvem para o dispositivo para o aplicativo do dispositivo por meio do Hub IoT. A função printResultFor de retorno de chamada definida na seção anterior recebe as informações de confirmação de entrega.

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

Este exemplo mostra como enviar uma mensagem para o seu dispositivo e lidar com a mensagem de feedback quando o dispositivo reconhece a mensagem da nuvem para o 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'));
  }
});

Exemplo de mensagem de envio do SDK

send_c2d_message.js - Envie mensagens C2D para um dispositivo através do Hub IoT.

Política de reconexão de conexão

Este artigo não demonstra uma política de repetição de mensagem para o dispositivo para conexão do Hub IoT ou aplicativo externo para conexão do Hub IoT. No código de produção, você deve implementar políticas de repetição de conexão conforme descrito em Gerenciar reconexões de dispositivo para criar aplicativos resilientes.

Tempo de retenção de mensagens, tentativas de repetição e contagem máxima de entrega

Conforme descrito em Enviar mensagens da nuvem para o dispositivo do Hub IoT, você pode exibir e configurar padrões para os seguintes valores de mensagem usando as opções de configuração do Hub IoT do portal ou a CLI do Azure. Essas opções de configuração podem afetar a entrega de mensagens e comentários.

  • TTL padrão (tempo de vida) - A quantidade de tempo que uma mensagem está disponível para um dispositivo consumir antes de expirar pelo Hub IoT.
  • Tempo de retenção de feedback - A quantidade de tempo que o Hub IoT retém o feedback para expiração ou entrega de mensagens da nuvem para o dispositivo.
  • O número de vezes que o Hub IoT tenta entregar uma mensagem da nuvem para o dispositivo para um dispositivo.