Enviar e receber mensagens da nuvem para o dispositivo

Receber mensagens da nuvem para o dispositivo

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

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

• Sondagem: o aplicativo de dispositivo verifica se há novas mensagens do Hub IoT usando um loop de código (por exemplo, um loop while ou for). 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 os métodos e as propriedades necessários para receber mensagens do Hub IoT.

Por exemplo:

static DeviceClient deviceClient;

Fornecer os parâmetros de conexão

Forneça a cadeia de conexão primária do Hub IoT e a identificação do dispositivo para DeviceClient usando o método CreateFromConnectionString. Além da cadeia de conexão primária do Hub IoT necessária, o método CreateFromConnectionString 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 é o padrão. Para ver todos os valores disponíveis, consulte Enum TransportType.
• transportSettings – Interface usada para definir várias configurações específicas de transporte para DeviceClient e ModuleClient. Para obter mais informações, consulte interface ITransportSettings.
• ClientOptions – opções que permitem a configuração da instância cliente do dispositivo ou do módulo durante a inicialização.

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

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

Sondagem

A sondagem usa ReceiveAsync para verificar se há mensagens.

Uma chamada para ReceiveAsync pode executar estes formulários:

• ReceiveAsync() - Aguarda o período de tempo limite padrão para uma mensagem antes de continuar.
• ReceiveAsync (Timespan) - Recebe uma mensagem da fila de dispositivos usando um tempo limite específico.
• ReceiveAsync (CancellationToken) - Recebe uma mensagem da fila de dispositivos 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 método ReceiveAsync retorna imediatamente. O padrão com suporte para as mensagens da nuvem para dispositivo com HTTP 1 são os dispositivos conectados intermitentemente que verificam mensagens com pouca frequência (no mínimo a cada 25 minutos). Emitir mais recebimentos de HTTP 1 resulta na limitação das solicitações pelo Hub IoT. Para obter mais informações sobre as diferenças no suporte a MQTT, AMQP e HTTP 1, consulte Diretrizes de comunicação da nuvem para dispositivo e Escolher 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 é processada com êxito e 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 é concluído com êxito, independentemente do protocolo de transporte sendo usado.

Abandono de mensagens, rejeição ou tempo limite

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

• Abandonar uma mensagem chamando AbandonAsync. Isso faz com que o Hub IoT mantenha a mensagem na fila de dispositivos para um consumo futuro.
• Rejeitar uma mensagem chamando RejectAsync. Isso remove permanentemente a mensagem da fila de dispositivos.

Se algo impedir o dispositivo de concluir, abandonar ou rejeitar a mensagem, o Hub IoT, após um tempo limite fixo, colocará a mensagem na fila de entrega novamente. Por esse motivo, a lógica de processamento de mensagem no aplicativo de dispositivo deve ser idempotente, de modo que receber a mesma mensagem várias vezes produza o mesmo resultado.

Para obter mais informações sobre o ciclo de vida de mensagem da nuvem para dispositivo e como o Hub IoT processa mensagens de nuvem para dispositivo, confira Enviar mensagens de nuvem para dispositivo por meio de um Hub IoT.

Loop de sondagem

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

Se usar ReceiveAsync com um valor de tempo limite ou o tempo limite padrão, no loop cada chamada para ReceiveAsync aguardará o período de tempo limite especificado. Se ReceiveAsync atingir o tempo limite, um valor null 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 notifica o Hub IoT para excluir a mensagem especificada da fila de mensagens com base no parâmetro Task.

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

Retorno de Chamada

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

Usando o retorno de chamada, o aplicativo de dispositivo configura um método de manipulador de mensagens usando SetReceiveMessageHandlerAsync. O manipulador de mensagens é chamado e uma mensagem é recebida. A criação de um método de retorno de chamada para receber mensagens acaba com a necessidade de sondar continuamente as mensagens recebidas.

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

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

A opção de protocolo Http1 não dá suporte aos retornos de chamada, pois os métodos do SDK precisariam sondar as mensagens recebidas de qualquer maneira, o que anula o princípio do retorno de chamada.

Neste exemplo, SetReceiveMessageHandlerAsync configura um método de manipulador de retorno de chamada denominado 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 da mensagem de recebimento

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

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

Exemplo de mensagem de recebimento do SDK

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

Envie mensagens da nuvem 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 da Internet das Coisas do Azure para .NET. Conforme 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 codificado com um dispositivo de destino. O Hub IoT armazena as 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 comentários de entrega de uma mensagem enviada ao Hub IoT destinada à entrega do dispositivo por meio da fila de mensagens.

Declarar um objeto ServiceClient

ServiceClient inclui os métodos e as propriedades necessários 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 usando o método CreateFromConnectionString. Além da cadeia de conexão primária do Hub IoT necessária, o método CreateFromConnectionString pode ser sobrecarregado para incluir estes parâmetros opcionais:

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

Este exemplo cria o objeto ServiceClient 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 por meio da nuvem (Hub IoT) para o dispositivo. A chamada é feita usando o protocolo AMQP.

sendAsync usa estes parâmetros:

• deviceID – identificador da cadeia de caracteres do dispositivo de destino.
• message – mensagem da nuvem para o dispositivo. A mensagem é do tipo Message e pode ser formatada de acordo.
• timeout – valor do 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 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);

Receber comentários 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 de informação, repetição ou compensação. Uma descrição completa das operações e das propriedades de comentários de mensagens é descrita em Comentários da mensagem.

Para receber comentários de entrega de mensagens:

• Criar o objeto feedbackReceiver
• Enviar mensagens usando o parâmetro Ack
• Aguardar 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 comentários.

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 comentários de entrega. A propriedade Ack pode ser um destes valores:

• none (padrão): nenhuma mensagem de comentários é gerada.

• Positive: receba uma mensagem de comentários se a mensagem foi concluída.

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

• Full: comentários sobre os resultados Positive e Negative.

Neste exemplo, a propriedade Ack é definida para Full, solicitando comentários positivos ou negativos de entrega para uma mensagem.

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

Aguardar para receber comentários

Defina CancellationToken. Depois, em um loop, chame ReceiveAsync repetidamente, verificando se há mensagens de comentários de entrega. Cada chamada para ReceiveAsync aguarda o período de tempo limite definido para o objeto ServiceClient.

• Se um tempo limite de ReceiveAsync expirar sem nenhuma mensagem recebida, ReceiveAsync retornará null e o loop continuará.
• Quando uma mensagem é recebida, um objeto Task é retornado por ReceiveAsync que deve ser passado para CompleteAsync junto com o token de cancelamento. Uma chamada para CompleteAsync exclui a mensagem enviada especificada da fila de mensagens com base no parâmetro Task.
• 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 inspecionar os detalhes da exceção e tomar as medidas necessárias.

Por exemplo:

• Se for uma exceção de rede, você poderá repetir 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 das solicitações ou atualize a unidade de escala da instância do hub. Consulte Cotas e limitação do Hub IoT para obter detalhes.

Política de repetição da mensagem de envio

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

Exemplo de mensagem de envio do SDK

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

Receber mensagens da nuvem para o dispositivo

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

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

Importar bibliotecas do SDK do Java da Internet das Coisas do Azure

O código referenciado neste artigo usa estas bibliotecas do 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 de objeto DeviceClient requer estes parâmetros:

• connString – a cadeia de conexão do dispositivo IoT. A cadeia de conexão é um conjunto de pares de chave-valor separados por ';', com as chaves e os valores separados com '='. Deve conter valores para estas chaves: HostName, DeviceId, and SharedAccessKey.
• Protocolo de transporte – a conexão DeviceClient pode usar um dos seguintes protocolos de transporte IoTHubClientProtocol. AMQP é o mais versátil, permite verificar as mensagens com frequência e permite a rejeição e o cancelamento de mensagens. O MQTT não dá suporte a 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 – nome do método de retorno de chamada. Pode ser null.
• context – um contexto opcional do tipo object. Use null se não for especificado.

Neste exemplo, um método callback denominado 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 valor retornado IotHubMessageResult.COMPLETE notifica o Hub IoT de que a mensagem é processada com êxito e a mensagem pode ser removida com segurança da fila de dispositivos. O dispositivo deve retornar IotHubMessageResult.COMPLETE quando o processamento conclui com êxito, notificando o Hub IoT de que a mensagem deve ser removida da fila de mensagens, independentemente do protocolo sendo usado.

  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 de entrada para um dispositivo deva ser recebido com êxito e resultar em IotHubMessageResult.COMPLETE, talvez seja necessário abandonar ou rejeitar uma mensagem.

• Com AMQP e HTTPS, mas não MQTT, o aplicativo pode:
  • A mensagem IotHubMessageResult.ABANDON. O Hub IoT recoloca na fila e envia novamente mais tarde.
  • A mensagem IotHubMessageResult.REJECT. O Hub IoT não recoloca na fila a mensagem e remove-a permanentemente da fila de mensagens.
• Os clientes que usam MQTT ou MQTT_WS não podem ABANDON ou REJECT as mensagens.

Se algo impedir o dispositivo de concluir, abandonar ou rejeitar a mensagem, o Hub IoT, após um tempo limite fixo, colocará a mensagem na fila de entrega novamente. Por esse motivo, a lógica de processamento de mensagem no aplicativo de dispositivo deve ser idempotente, de modo que receber a mesma mensagem várias vezes produza o mesmo resultado.

Para obter mais informações sobre o ciclo de vida de mensagem da nuvem para dispositivo e como o Hub IoT processa mensagens de nuvem para dispositivo, confira Enviar mensagens de nuvem para dispositivo por meio de um Hub IoT.

Criar o método de retorno de chamada de 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. Dessa forma, o aplicativo pode detectar uma conexão de mensagens desativada e tentar se reconectar.

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

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

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

Chame connectionStatusChangeContext.getNewStatus() para obter o estado de conexão atual.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

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

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

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

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Chame connectionStatusChangeContext.getCause() para descobrir o motivo da alteração do status da conexão. getCause() pode retornar null se nenhuma informação está disponível.

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

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

Abrir 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 e para um Hub IoT de forma assíncrona. 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 com o SDK do IoT do Microsoft Azure para Java, que se conecta ao hub IoT e recebe mensagens da nuvem para o dispositivo.

Envie mensagens da nuvem para o dispositivo

Esta seção descreve como enviar uma mensagem da nuvem para o dispositivo usando a classe ServiceClient do SDK da Internet das Coisas do Azure 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 codificado com um dispositivo de destino. O Hub IoT armazena as 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 comentários de entrega de uma mensagem enviada ao Hub IoT destinada à entrega do dispositivo por meio da fila de mensagens.

Adicionar a instrução de dependência

A adição da dependência permite que você use o pacote iothub-java-service-client no aplicativo para se comunicar com o serviço do 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 estas instruções de importação para usar o SDK do Java da Internet das Coisas do Azure e o manipulador de exceção.

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 da camada do aplicativo usado pelo cliente de serviço para se comunicar com um Hub IoT.

IotHubServiceClientProtocol aceita apenas a enumeração AMQPS ou AMQPS_WS.

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

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

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

serviceClient.open();

Abrir um receptor de comentários para os comentários de entrega de mensagens

Você pode usar FeedbackReceiver para obter a entrega de mensagens enviadas para os comentários do Hub IoT. Um FeedbackReceiver é um receptor especializado cujo método Receive retorna FeedbackBatch em vez de Message.

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

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

Adicionar as propriedades de mensagem

Opcionalmente, você pode usar setProperties para adicionar as propriedades de mensagem. Essas propriedades são incluídas na mensagem enviada ao 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 da nuvem para o dispositivo" é entregue.

Use setDeliveryAcknowledgement para solicitar a entrega/não entrega para a confirmação da fila de mensagens do 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 Send (não assíncrono), mas essa função é sincronizada internamente para que apenas uma operação de envio seja permitida por 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 comentários sobre a entrega de mensagens

Depois que uma mensagem é enviada do aplicativo, o aplicativo pode chamar receber 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 retorna um objeto FeedbackBatch que contém as propriedades dos comentários de entrega de mensagens que podem ser examinadas.

Este exemplo cria o receptor FeedbackBatch e as chamadas getEnqueuedTimeUtc, imprimindo o tempo de fila da mensagem.

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

Exemplos de mensagem de envio do SDK

• Exemplo de cliente do serviço – exemplo de mensagem de envio, nº 1.

• Exemplo de cliente do serviço – exemplo de mensagem de envio, nº 2.

Instalar a biblioteca do SDK da Internet das Coisas do Azure

Instale a biblioteca do SDK azure-iot-device em seu computador de desenvolvimento antes de chamar qualquer código relacionado:

pip install azure-iot-device

Há duas classes do SDK do Python que são usadas para enviar mensagens de e para os dispositivos IoT. Os métodos de tratamento de mensagens dessas classes são descritos nas seções nesta 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 as operações do Gerenciador de Registros do Hub IoT. Neste artigo, os métodos dessa classe mostram como se conectar ao Hub IoT e enviar uma mensagem para um dispositivo.

Receber mensagens da nuvem para o dispositivo

Esta seção descreve como receber mensagens da nuvem para o dispositivo usando a classe IoTHubDeviceClient no SDK da Internet das Coisas do Azure 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, em seguida, configurar um manipulador de mensagens de retorno de chamada para processar as mensagens de entrada do Hub IoT.

Importar o objeto IoTHubDeviceClient

Adicione uma linha de código para importar as funções IoTHubDeviceClient 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 conectar IoTHubDeviceClient a um dispositivo usando um destes métodos:

• cadeia de caracteres de token SAS
• autenticação de chave simétrica
• autenticação de certificado X.509

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

Manipular reconexão

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

Criar um manipulador de mensagens

Crie a função do manipulador de mensagens para processar as mensagens de entrada 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 do manipulador de mensagens ao objeto IoTHubDeviceClient.

Neste exemplo, um método de manipulador de mensagens denominado message_handler é anexado ao objeto IoTHubDeviceClient client. O objeto client aguarda para receber uma mensagem de nuvem para dispositivo a partir de um Hub IoT. Esse código aguarda até 300 segundos (5 minutos) por uma mensagem ou sai se uma tecla no teclado é 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

Mensagem de recebimento – receba mensagens C2D (nuvem para dispositivo) enviadas do Hub IoT do Azure para um dispositivo.

Envie mensagens da nuvem para o dispositivo

Esta seção descreve como enviar uma mensagem da nuvem para o dispositivo usando a classe IoTHubRegistryManager do SDK da Internet das Coisas do Azure 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 codificado com um dispositivo de destino. O Hub IoT armazena as 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 instrução import a seguir. IoTHubRegistryManager inclui APIs para as operações do Gerenciador de Registros do Hub IoT.

from azure.iot.hub import IoTHubRegistryManager

Conectar o gerenciador de registros 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)

Compilar e enviar uma mensagem

Use send_c2d_message para enviar uma mensagem por meio da nuvem (Hub IoT) para o dispositivo.

send_c2d_message usa estes parâmetros:

• deviceID – identificador da cadeia de caracteres do dispositivo de destino.
• message – mensagem da nuvem para o dispositivo. A mensagem é do tipo str (cadeia de caracteres).
• properties – uma coleção opcional de propriedades do tipo dict. As propriedades podem conter propriedades do aplicativo e propriedades do sistema. O valor padrão é {}.

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 de nuvem para dispositivo.

Instalar os pacotes de mensagens do Node.js

Execute estes comandos para instalar os pacotes azure-iot-device e azure-iothub em seu computador 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 os dispositivos IoT. Este artigo descreve o código de classe Client que recebe mensagens do Hub IoT.

O pacote azure-iothub contém objetos que fazem interface com o Hub IoT. Este artigo descreve o código de classe Client que envia uma mensagem de um aplicativo para um dispositivo por meio do 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 da Internet das Coisas do Azure para Node-js.

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

Criar um módulo cliente

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

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

Escolher um protocolo de transporte

O objeto Client dá suporte a esses protocolos:

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

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

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

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

Funcionalidades 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:

• Concluir – para concluir uma mensagem, o serviço que enviou a mensagem da nuvem para o dispositivo é notificado de que a mensagem é recebida. O Hub IoT remove a mensagem da fila de mensagens. O método assume a forma 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 do dispositivo. O método assume a forma client.reject(message, callback function).
• Abandonar – para abandonar uma mensagem, o Hub IoT tenta reenviá-la imediatamente. O Hub IoT mantém a mensagem na fila do dispositivo para o consumo futuro. O método assume a forma client.abandon(message, callback function).

MQTT

O MQTT não dá suporte a funções de mensagens completas, rejeitadas ou abandonadas. Em vez disso, o MQTT aceita uma mensagem por padrão e a mensagem é removida da fila de mensagens do Hub IoT.

Tentativas de novo envio

Se algo impedir o dispositivo de concluir, abandonar ou rejeitar a mensagem, o Hub IoT, após um tempo limite fixo, colocará a mensagem na fila de entrega novamente. Por esse motivo, a lógica de processamento de mensagem no aplicativo de dispositivo deve ser idempotente, de modo que receber a mesma mensagem várias vezes produza o mesmo resultado.

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

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

• connStr – uma cadeia de conexão que encapsula as permissões de "conexão de dispositivo" para um hub IoT. A cadeia de conexão contém o nome do host, a identidade do dispositivo e chave de acesso Compartilhada neste formato: "HostName=<iothub_host_name>;DeviceId=<device_id>; SharedAccessKey=<device_key>"
• transportCtor – 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 é recebida com êxito, se usar o transporte AMQP ou HTTP, chame o método client.complete para informar ao Hub IoT que a mensagem pode ser removida da fila de mensagens.

Por exemplo, esse manipulador de mensagens imprime a ID da mensagem e o corpo da mensagem no console, em seguida, chama client.complete para notificar o Hub IoT de que ele processou a mensagem e que ela pode ser removida com segurança da fila do dispositivo. A chamada para complete não será necessária se você estiver usando o transporte MQTT e poderá ser omitida. Uma chamada paracomplete é necessária para 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 para a 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 estes 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);

Abrir 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 código de manipulador de chamadas e de erros.

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 hub IoT e recebe mensagens da nuvem para o dispositivo.

Envie mensagens da nuvem para o dispositivo

Esta seção descreve como enviar uma mensagem da nuvem para o dispositivo usando o pacote azure-iothub do SDK da Internet das Coisas do Azure para Node.js. Conforme 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 codificado com um dispositivo de destino. O Hub IoT armazena as 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 comentários de entrega de uma mensagem enviada ao Hub IoT destinada à entrega do dispositivo por meio da fila de mensagens.

Carregar os módulos do cliente e da mensagem

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

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

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

Criar o objeto Cliente

Crie Client usando fromConnectionString com estes parâmetros:

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

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

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

Abrir a conexão Cliente

Use o método Clientopen para abrir uma conexão entre um dispositivo IoT e o Hub IoT.

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

Neste exemplo, o método open 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 chamada null 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 de nuvem para dispositivo. A funcionalidade da mensagem ocorre como em AMQP, MQTT e HTTP.

O objeto de mensagem dá suporte a várias propriedades, incluindo estas. Consulte as propriedades message para obter uma lista completa.

• ack – comentários de entrega. Descritos na próxima seção.
• properties – um mapa que contém as chaves da cadeia de caracteres e os valores para armazenar as propriedades de mensagem personalizadas.
• messageId – usado para correlacionar a comunicação bidirecional.

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

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

Confirmação 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 de informação, repetição ou compensação. Uma descrição completa das operações e das propriedades de comentários de mensagens é descrita em Comentários da mensagem.

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

• none (padrão): nenhuma mensagem de comentários é gerada.

• sent: receba uma mensagem de comentários se a mensagem foi concluída.

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

• full: comentários para resultados enviados e não enviados.

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

message.ack = 'full';

Vincular o receptor de comentários da mensagem

A função de retorno de chamada do receptor de comentários de mensagem está vinculada a Client usando getFeedbackReceiver.

O receptor de comentários da mensagem recebe dois argumentos:

• Objeto Error (pode ser null)
• Objeto AmqpReceiver – emite eventos quando novas mensagens de comentários são recebidas pelo cliente.

Essa função de exemplo recebe e imprime uma mensagem de comentários de entrega no 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 comentários receiveFeedback ao objeto Client de serviço usando getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Definir um manipulador dos resultados de conclusão da mensagem

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

Essa função de exemplo imprime os resultados da operação send da mensagem no console. Neste exemplo, a função printResultFor é fornecida como um parâmetro para a função send 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 de nuvem para dispositivo para o aplicativo de dispositivo por meio do Hub IoT.

send dá suporte a estes parâmetros:

• deviceID – identificação do dispositivo de destino.
• message – corpo da mensagem a ser enviada ao dispositivo.
• done – a função opcional a chamar quando a operação é concluída. Done é chamado com dois argumentos:
  • Objeto Error (pode ser null).
  • objeto de resposta específico do transporte útil para o registro em log ou a depuração.

Esse código chama send para enviar uma mensagem da nuvem para o dispositivo para o aplicativo de dispositivo por meio do Hub IoT. A função de retorno de chamada printResultFor 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 seu dispositivo e lidar com a mensagem de comentários 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 por meio do Hub IoT.