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

Artigo
06/01/2023

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

Este artigo mostra-lhe como:

Enviar mensagens de cloud para dispositivo (C2D) a partir do back-end da solução para um único dispositivo através de Hub IoT
Receber mensagens da cloud para o dispositivo num dispositivo
Pedir a confirmação da entrega (feedback), a partir do back-end da solução, para mensagens enviadas para um dispositivo a partir de Hub IoT

Nota

As funcionalidades descritas neste artigo só estão disponíveis no escalão padrão de Hub IoT. Para obter mais informações sobre as camadas de Hub IoT básicas e padrão/gratuitas, consulte Escolher o escalão de Hub IoT adequado para a sua solução.

No final deste artigo, vai executar duas aplicações de consola .NET.

MessageReceiveSample: uma aplicação de dispositivo de exemplo incluída com o SDK IoT do Microsoft Azure para .NET, que se liga ao seu hub IoT e recebe mensagens da cloud para o dispositivo.
SendCloudToDevice: uma aplicação de serviço que envia uma mensagem da cloud para o dispositivo para a aplicação do dispositivo através de Hub IoT e, em seguida, recebe a confirmação da entrega.

Nota

Hub IoT tem suporte do SDK para muitas plataformas e idiomas de dispositivos (C, Java, Python e JavaScript) através de SDKs de dispositivos IoT do Azure.

Pode encontrar mais informações sobre mensagens da cloud para o dispositivo no D2C e nas Mensagens C2D com Hub IoT.

Pré-requisitos

Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Um hub IoT na sua subscrição do Azure. Se ainda não tiver um hub, pode seguir os passos em Criar um hub IoT.
Um dispositivo registado no hub IoT. Se ainda não registou um dispositivo, registe um no portal do Azure.
Este artigo utiliza código de exemplo do SDK do Azure IoT para C#.
- Transfira ou clone o repositório do SDK do GitHub para o seu computador de desenvolvimento.
- Certifique-se de que o .NET Core 3.0.0 ou superior está instalado no seu computador de desenvolvimento. Verifique a sua versão ao executar dotnet --version e transferir o .NET , se necessário.
Certifique-se de que a porta 8883 está aberta na firewall. O exemplo de dispositivo neste artigo utiliza o protocolo MQTT, que comunica através da porta 8883. Esta porta pode ser bloqueada em alguns ambientes de rede empresarial e educacional. Para obter mais informações e formas de resolver este problema, veja Ligar ao Hub IoT (MQTT).
Visual Studio.

Obter a cadeia de ligação do dispositivo

Neste artigo, vai executar uma aplicação de exemplo que simula um dispositivo, que recebe mensagens da cloud para o dispositivo enviadas através da sua Hub IoT. A aplicação de exemplo MessageReceiveSample incluída com o SDK IoT do Microsoft Azure para .NET liga-se ao hub IoT e atua como o seu dispositivo simulado. O exemplo utiliza a cadeia de ligação primária do dispositivo registado no hub IoT.

Para obter a cadeia de ligação primária de um dispositivo registado no hub IoT, siga estes passos:

Na portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos onde o hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel esquerdo do hub IoT, em Gestão de Dispositivos, selecione Dispositivos.
Na lista de dispositivos, selecione o dispositivo adequado.
Copie a cadeia de ligação Primária e guarde o valor.

Receber mensagens na aplicação do dispositivo

Nesta secção, execute a aplicação de exemplo MessageReceiveSample para receber mensagens C2D enviadas através do hub IoT. Abra uma nova linha de comandos e navegue para a pasta azure-iot-sdk-csharp\iothub\device\samples\getting started\MessageReceiveSample , na pasta onde expandiu o SDK C# do Azure IoT. Execute os seguintes comandos, substituindo o valor do {Your device connection string} marcador de posição pela cadeia de ligação do dispositivo que copiou do dispositivo registado no hub IoT.

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

O resultado seguinte é da aplicação de dispositivo de exemplo depois de ter iniciado e ligado 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.

A aplicação de dispositivo de exemplo consulta as mensagens com os métodos ReceiveAsync e CompleteAsync . O ReceiveC2dMessagesPollingAndCompleteAsync método utiliza o ReceiveAsync método, que devolve assíncronamente a mensagem recebida no momento em que o dispositivo recebe a mensagem. ReceiveAsync devolve nulo após um período de tempo limite especificado. Neste exemplo, é utilizada a predefinição de um minuto. Quando o dispositivo recebe um valor nulo, deve continuar a aguardar novas mensagens. Este requisito é a razão pela qual a aplicação de exemplo inclui o seguinte bloco de código no ReceiveC2dMessagesPollingAndCompleteAsync método:

   if (receivedMessage == null)
   {
      continue;
   }

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

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

Abandone uma mensagem, o que resulta em Hub IoT manter a mensagem na fila do dispositivo para consumo futuro.
Rejeitar uma mensagem, que remove permanentemente a mensagem da fila do dispositivo.

Se ocorrer algo que impeça o dispositivo de concluir, abandonar ou rejeitar a mensagem, Hub IoT colocará a mensagem novamente em fila após um período de tempo limite fixo. Por este motivo, a lógica de processamento de mensagens na aplicação do dispositivo tem de 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 das mensagens da cloud para o dispositivo e como Hub IoT processa mensagens da cloud para o dispositivo, consulte Enviar mensagens da cloud para o dispositivo a partir de um hub IoT.

Nota

Ao utilizar HTTPS em vez de MQTT ou AMQP como um transporte, o ReceiveAsync método regressa imediatamente. O padrão suportado para mensagens da cloud para o dispositivo com HTTPS é dispositivos ligados intermitentemente que verificam mensagens com pouca frequência (um mínimo de cada 25 minutos). Emitir mais HTTPS recebe resultados em Hub IoT limitação dos pedidos. Para obter mais informações sobre as diferenças entre o suporte MQTT, AMQP e HTTPS, veja Orientação de comunicações da cloud para dispositivo e Escolha um protocolo de comunicação.

Obter a cadeia de ligação do hub IoT

Neste artigo, vai criar um serviço de back-end para enviar mensagens da cloud para o dispositivo através da sua Hub IoT. Para enviar mensagens da cloud para o dispositivo, o seu serviço precisa da permissão de ligação do serviço . Por predefinição, todas as Hub IoT são criadas com uma política de acesso partilhado denominada serviço que concede esta permissão.

Para obter a cadeia de ligação Hub IoT para a política de serviço, siga estes passos:

Na portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos onde 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 partilhado.
Na lista de políticas, selecione a política de serviço .
Copie a cadeia de ligação Primária e guarde o valor.

Para obter mais informações sobre Hub IoT políticas e permissões de acesso partilhado, veja Controlo de acesso e permissões.

Enviar uma mensagem da cloud para o dispositivo

Nesta secção, vai criar uma aplicação de consola .NET que envia mensagens da cloud para o dispositivo para a aplicação de dispositivo simulado. Precisa do ID do dispositivo do seu dispositivo e da cadeia de ligação do hub IoT.

No Visual Studio, selecione Ficheiro>Novo>Projeto. Em Criar um novo projeto, selecione Aplicação de Consola (.NET Framework) e, em seguida, selecione Seguinte.
Dê um nome ao projeto SendCloudToDevice e, em seguida, selecione Seguinte.
Aceite a versão mais recente do .NET Framework. Selecione Create (Criar) para criar o projeto.
No Explorador de Soluções, clique com o botão direito do rato no novo projeto e, em seguida, selecione Gerir Pacotes NuGet.
Em Gerir Pacotes NuGet, selecione Procurar e, em seguida, procure e selecione Microsoft.Azure.Devices. Selecione Instalar.

Este passo transfere, instala e adiciona uma referência ao pacote NuGet do SDK do serviço IoT do Azure.
Adicione a seguinte using instrução na parte superior do ficheiro Program.cs .
```
using Microsoft.Azure.Devices;
```
Adicione os seguintes campos à classe Programa. Substitua o valor do {iot hub connection string} marcador de posição pela cadeia de ligação do hub IoT que anotou anteriormente em Obter a cadeia de ligação do hub IoT. Substitua o valor do {device id} marcador de posição pelo ID do dispositivo registado 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 para o seu 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();

Prima F5 para iniciar a sua aplicação de serviço de exemplo. Selecione a janela SendCloudToDevice e prima Enter. Deverá ver a mensagem recebida pela aplicação de dispositivo de exemplo, conforme mostrado no exemplo de saída seguinte.

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 feedback sobre a entrega

É possível pedir confirmações de entrega (ou expiração) de Hub IoT para cada mensagem da cloud para o dispositivo. Esta opção permite que o back-end da solução informe, repita ou ressoe facilmente a lógica. Para obter mais informações sobre o feedback da cloud para o dispositivo, veja D2C e C2D Messaging with Hub IoT (Mensagens D2C e C2D com Hub IoT).

Nesta secção, vai modificar a aplicação de serviço de exemplo SendCloudToDevice para pedir feedback e recebê-la do hub IoT.

No Visual Studio, no projeto SendCloudToDevice , adicione o seguinte método à classe Programa .

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

Tenha em atenção que este padrão de receção é o mesmo utilizado para receber mensagens da aplicação do dispositivo da cloud para dispositivo.

Adicione a seguinte linha no método Main , logo a seguir serviceClient = ServiceClient.CreateFromConnectionString(connectionString)a .
```
ReceiveFeedbackAsync();
```
Para pedir feedback para a entrega da mensagem da cloud para o dispositivo, tem de especificar uma propriedade no método SendCloudToDeviceMessageAsync . Adicione a seguinte linha imediatamente a seguir à var commandMessage = new Message(...); linha.
```
commandMessage.Ack = DeliveryAcknowledgement.Full;
```
Certifique-se de que a aplicação de dispositivo de exemplo está em execução e, em seguida, execute a aplicação de serviço de exemplo ao premir F5. Selecione a janela da consola SendCloudToDevice e prima Enter. Deverá ver a mensagem a ser recebida pela aplicação de dispositivo de exemplo e, após alguns segundos, a mensagem de feedback a ser recebida pela sua aplicação SendCloudToDevice . A seguinte saída mostra a mensagem de feedback recebida pela aplicação de serviço de exemplo:
```
Send Cloud-to-Device message


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

Received feedback: Success
```

Nota

Para simplificar, este artigo não implementa nenhuma política de repetição. No código de produção, deve implementar políticas de repetição, como o recuo exponencial, conforme sugerido no processamento de falhas transitórias.

Passos seguintes

Neste artigo, aprendeu a enviar e receber mensagens da cloud para o dispositivo.

Para saber mais sobre as mensagens da cloud para o dispositivo, veja Enviar mensagens da cloud para o dispositivo a partir de um hub IoT.
Para saber mais sobre Hub IoT formatos de mensagens, consulte Criar e ler Hub IoT mensagens.

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

Pré-requisitos

Obter a cadeia de ligação do dispositivo

Receber mensagens na aplicação do dispositivo

Obter a cadeia de ligação do hub IoT

Enviar uma mensagem da cloud para o dispositivo

Receber feedback sobre a entrega

Passos seguintes

Recursos adicionais