Enviar mensagens da nuvem para o dispositivo com o Hub IoT (.NET)

Artigo
06/01/2023

O Hub IoT do Azure é um serviço totalmente gerenciado que ajuda a permitir comunicações bidirecionais confiáveis e seguras entre milhões de dispositivos e um back-end de solução.

Este artigo mostra como:

Envie mensagens da nuvem para dispositivo (C2D) do back-end da sua solução para um único dispositivo através do Hub IoT
Receber mensagens da nuvem para dispositivo em um dispositivo
Solicite confirmação de entrega (comentários), do back-end da sua solução, para as mensagens enviadas a um dispositivo do Hub IoT

Observação

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

No fim deste artigo, você executará dois aplicativos de console .NET.

MessageReceiveSample: um aplicativo do dispositivo de amostra incluído no SDK de Internet das Coisas do Azure para .NET, que se conecta ao seu hub IoT e recebe mensagens de nuvem para dispositivo.
SendCloudToDevice: um aplicativo de serviço que envia uma mensagem da nuvem para o aplicativo do dispositivo através do Hub IoT e, em seguida, recebe sua confirmação de entrega.

Observação

O Hub IoT tem suporte a SDK para várias plataformas de dispositivo e linguagens (C, Java, Python e Javascript) por meio dos SDKs do dispositivo IoT do Azure.

É possível encontrar mais informações sobre mensagens de nuvem para dispositivo em Mensagens de dispositivo para nuvem e nuvem para dispositivo com o Hub IoT.

Pré-requisitos

Uma assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.
Um dispositivo registrado em seu hub IoT. Se você ainda não registrou um dispositivo, registre um no portal do Azure.
Este artigo usa códigos de exemplo do SDK de Internet das Coisas do Azure para C#.
- Baixe ou clone o repositório SDK do GitHub do seu computador de desenvolvimento.
- Certifique-se de que o .NET Core 3.0.0 ou posterior esteja instalado no computador de desenvolvimento. Verifique sua versão executando dotnet --version e baixe o .NET, se necessário.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).
Visual Studio.

Obter a cadeia de conexão do dispositivo

Neste artigo, você executa um aplicativo de amostra que simula um dispositivo, que recebe mensagens da nuvem para dispositivo enviadas através do seu Hub IoT. O aplicativo de amostra MessageReceiveSample incluído no SDK de Internet das Coisas do Azure para .NET se conecta ao seu hub de IoT e atua como seu dispositivo simulado. A amostra usa a cadeia de conexão primária do dispositivo registrado no seu hub IoT.

Para obter a cadeia de conexão primária de um dispositivo registrado no seu hub IoT, siga estas etapas:

No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do seu hub IoT, em Gerenciamento de Dispositivos, selecione Dispositivos.
Na lista de dispositivos, selecione o dispositivo apropriado.
Copie a Cadeia de conexão primária e salve o valor.

Receber mensagens no aplicativo do dispositivo

Nesta seção, execute o aplicativo do dispositivo de amostra MessageReceiveSample para receber mensagens C2D enviadas através do seu hub IoT. Abra um novo prompt de comando e navegue para a pasta azure-iot-sdk-csharp\iothub\device\samples\getting started\MessageReceiveSample, na pasta em que você expandiu o SDK do C# de Internet das Coisas do Azure. Execute os comandos a seguir, substituindo o valor do espaço reservado {Your device connection string} pela cadeia de conexão do dispositivo que você copiou do dispositivo registrado no seu hub IoT.

dotnet restore
dotnet run --c "{Your device connection string}"

A saída a seguir é do aplicativo do dispositivo de amostra depois que ele é iniciado e conectado com êxito ao seu hub IoT:

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
     
5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.

O aplicativo do dispositivo de amostra pesquisa mensagens usando os métodos ReceiveAsync e CompleteAsync. O método ReceiveC2dMessagesPollingAndCompleteAsync usa o método ReceiveAsync, que retorna de forma assíncrona a mensagem recebida no momento em que o dispositivo recebe a mensagem. ReceiveAsync retorna nulo após um período de tempo limite especificável. Neste exemplo, o padrão de um minuto é usado. Quando o dispositivo recebe um nulo, ele deve continuar aguardando novas mensagens. Esse requisito é o motivo pelo qual o aplicativo de amostra inclui o seguinte bloco de código no método ReceiveC2dMessagesPollingAndCompleteAsync:

   if (receivedMessage == null)
   {
      continue;
   }

A chamada para o método CompleteAsync notifica o Hub IoT que a mensagem foi processada com êxito e que a mensagem pode ser removida com segurança da fila do dispositivo. O dispositivo deve chamar esse método quando seu processamento for concluído com êxito, independentemente do protocolo que esteja usando.

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

Abandonar temporariamente uma mensagem, fazendo com que um Hub IoT retenha a mensagem na fila do dispositivo para consumo futuro.
Rejeitar uma mensagem, o que irá removê-la permanentemente da fila de espera do dispositivo.

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.

Observação

Ao usar HTTPS em vez de MQTT ou AMQP como transporte, o método ReceiveAsync é retornado imediatamente. O padrão com suporte para mensagens da nuvem para dispositivo com HTTPS são dispositivos conectados intermitentemente que verificam mensagens com pouca frequência (no mínimo a cada 25 minutos). Emitir mais recebimentos de HTTPS resulta na limitação das solicitações pelo Hub IoT. Para obter mais informações sobre as diferenças entre o suporte a MQTT, AMQP e HTTPS, consulte Diretrizes de comunicação da nuvem para dispositivo e Escolher um protocolo de comunicação.

Obter a cadeia de conexão do hub IoT

Neste artigo, você criará um serviço de back-end para enviar mensagens de nuvem para dispositivo por meio do seu Hub IoT. Para enviar mensagens de nuvem para dispositivo, o serviço precisa da permissão conexão de serviço. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Para obter a cadeia de conexão do Hub IoT para a política de serviço, siga estas etapas:

No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do hub IoT, selecione Políticas de acesso compartilhado.
Na lista de políticas, selecione a política de serviço.
Copie a Cadeia de conexão primária e salve o valor.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Envie uma mensagem da nuvem para o dispositivo

Nesta seção, você cria um aplicativo do console .NET que envia mensagens da nuvem para dispositivo no aplicativo de dispositivo simulado. Você precisa da ID do dispositivo e da cadeia de conexão do hub IoT.

No Visual Studio, selecione Arquivo>Novo>Projeto. Em Criar um projeto, selecione Aplicativo de Console (.NET Framework) e, em seguida, selecione Próximo.
Nomeie o projeto SendCloudToDevice e selecione Avançar.
Aceite a versão mais recente do .NET Framework. Selecione Criar para criar o cluster.
No Gerenciador de Soluções, clique com o botão direito no projeto e escolha Gerenciar Pacotes NuGet.
Em Gerenciar Pacotes NuGet, selecione Procurar e, em seguida, pesquise e selecione Microsoft.Azure.Devices. Selecione Instalar.

Essa etapa baixa, instala e adiciona uma referência ao pacote NuGet do SDK do serviço IoT do Azure.
Adicione a seguinte instrução using na parte superior do arquivo Program.cs.
```
using Microsoft.Azure.Devices;
```
Adicione os seguintes campos à classe Program . Substitua o valor do espaço reservado {iot hub connection string} pela cadeia de conexão do hub IoT que você anotou anteriormente em Obter a cadeia de conexão do hub IoT. Substitua o valor do espaço reservado {device id} pela ID do dispositivo registrado no seu hub IoT.
```
static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";
static string targetDevice = "{device id}";
```

Adicione o seguinte método à classe Programa para enviar uma mensagem ao dispositivo.

private async static Task SendCloudToDeviceMessageAsync()
{
     var commandMessage = new
      Message(Encoding.ASCII.GetBytes("Cloud to device message."));
     await serviceClient.SendAsync(targetDevice, commandMessage);
}

Por fim, adicione as seguintes linhas ao método Main .

Console.WriteLine("Send Cloud-to-Device message\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Console.WriteLine("Press any key to send a C2D message.");
Console.ReadLine();
SendCloudToDeviceMessageAsync().Wait();
Console.ReadLine();

Pressione F5 para iniciar seu aplicativo do serviço de amostra. Selecione a janela SendCloudToDevice e pressione Enter. Você deve ver a mensagem recebida pelo aplicativo do dispositivo de amostra, conforme mostrado no exemplo de saída a seguir.

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.

5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.
5/22/2023 11:15:18 AM> Polling using ReceiveAsync() - received message with Id=
5/22/2023 11:15:18 AM> Received message: [Cloud to device message.]
        Content type:

5/22/2023 11:15:18 AM> Completed C2D message with Id=.

Receber comentários de entrega

É possível solicitar confirmações de entrega (ou expiração) do Hub IoT para cada mensagem de nuvem para dispositivo. Essa opção permite que o back-end da solução informe a lógica de repetição ou de compensação facilmente. Para obter mais informações sobre comentários da nuvem para o dispositivo, consulte Mensagens de dispositivo para nuvem e nuvem para dispositivo com o Hub IoT.

Nesta seção, você modifica o aplicativo de serviço de amostra do SendCloudToDevice para solicitar comentários e recebê-los do hub IoT.

No Visual Studio, no projeto SendCloudToDevice, adicione o método a seguir à classe Program.

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

     Console.WriteLine("\nReceiving c2d feedback from service");
     while (true)
     {
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         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);
     }
 }

É importante lembrar que o padrão de recebimento é o mesmo usado para receber mensagens da nuvem para o dispositivo do aplicativo do dispositivo.

Adicione a linha a seguir no método Main, logo após serviceClient = ServiceClient.CreateFromConnectionString(connectionString).
```
ReceiveFeedbackAsync();
```
Para solicitar comentários sobre a entrega da mensagem da nuvem para o dispositivo, você deve especificar uma propriedade no método SendCloudToDeviceMessageAsync . Adicione a seguinte linha, logo após a linha var commandMessage = new Message(...);.
```
commandMessage.Ack = DeliveryAcknowledgement.Full;
```
Verifique se o aplicativo do dispositivo de amostra está em execução e, em seguida, execute o aplicativo do serviço de amostra pressionando F5. Selecione a janela do console SendCloudToDevice e pressione Enter. Você verá a mensagem sendo recebida pelo aplicativo do dispositivo de amostra e, após alguns segundos, a mensagem de comentário sendo recebida pelo seu aplicativo SendCloudToDevice. A saída a seguir mostra a mensagem de comentário recebida pelo aplicativo do serviço de amostra:
```
Send Cloud-to-Device message


Receiving c2d feedback from service
Press any key to send a C2D message.

Received feedback: Success
```

Observação

Para simplificar, este artigo não implementa nenhuma política de repetição. No código de produção, você deve implementar políticas de repetição, como uma retirada exponencial, conforme sugerido em Tratamento de falhas transitórias.

Próximas etapas

Neste artigo, você aprendeu a enviar e receber mensagens de nuvem para dispositivo.

Para saber mais sobre mensagens da nuvem para o dispositivo, confira Enviar mensagens da nuvem para o dispositivo de um Hub IoT.
Para saber mais sobre o formato de mensagem do Hub IoT, confira Criar e ler mensagens do Hub IoT.

Enviar mensagens da nuvem para o dispositivo com o Hub IoT (.NET)

Pré-requisitos

Obter a cadeia de conexão do dispositivo

Receber mensagens no aplicativo do dispositivo

Obter a cadeia de conexão do hub IoT

Envie uma mensagem da nuvem para o dispositivo

Receber comentários de entrega

Próximas etapas

Recursos adicionais