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

Hub IoT do Azure é um serviço totalmente gerido que ajuda a permitir comunicações fiáveis e seguras bidirecionais entre milhões de dispositivos e uma solução traseira. O telemetria Enviar de um dispositivo para um quickstart do hub IoT mostra como criar um hub IoT, providenciar uma identidade de dispositivo no mesmo, e codificar uma aplicação de dispositivo que envia mensagens dispositivo-a-nuvem.

Nota

As funcionalidades descritas neste artigo estão disponíveis apenas no nível padrão de Hub IoT. Para obter mais informações sobre os níveis básico e standard/free Hub IoT, consulte escolha o nível Hub IoT certo.

Este tutorial baseia-se em Enviar telemetria de um dispositivo para um hub IoT. Mostra como fazer as seguintes tarefas:

  • A partir da parte de trás da sua solução, envie mensagens nuvem-dispositivo para um único dispositivo através de Hub IoT.

  • Receba mensagens nuvem-dispositivo num dispositivo.

  • A partir do final da sua solução, solicite o reconhecimento de entrega (feedback) para mensagens enviadas a um dispositivo a partir de Hub IoT.

Pode encontrar mais informações sobre mensagens cloud-to-device em Mensagens D2C e C2D com Hub IoT.

No final deste tutorial, executou duas aplicações de consola .NET.

  • SimuladoDevice. Esta aplicação conecta-se ao seu hub IoT e recebe mensagens nuvem-dispositivo. Esta aplicação é uma versão modificada da app criada em Enviar telemetria de um dispositivo para um hub IoT.

  • SendCloudToDevice. Esta aplicação envia uma mensagem nuvem-para-dispositivo para a aplicação do dispositivo através de Hub IoT e, em seguida, recebe o seu reconhecimento de entrega.

Nota

Hub IoT tem suporte SDK para muitas plataformas e idiomas de dispositivos, incluindo C, Java, Python e JavaScript, através de SDKs de dispositivoS Azure IoT. Para obter instruções passo a passo sobre como ligar o seu dispositivo ao código deste tutorial e, em geral, Hub IoT do Azure, consulte o guia de Hub IoT do desenvolvedor.

Pré-requisitos

  • Visual Studio

  • Uma conta ativa do Azure. Se não tiver uma conta, pode criar uma conta gratuita em apenas alguns minutos.

  • Certifique-se de que a porta 8883 está aberta na sua firewall. A amostra do dispositivo neste artigo utiliza o protocolo MQTT, que comunica através da porta 8883. Este porto pode ser bloqueado em alguns ambientes de rede corporativa e educacional. Para obter mais informações e formas de contornar este problema, consulte Connecting to Hub IoT (MQTT).

Receber mensagens na aplicação do dispositivo

Nesta secção, modifique a aplicação do dispositivo criada em Enviar telemetria de um dispositivo para um hub IoT para receber mensagens nuvem-dispositivo a partir do hub IoT.

  1. Em Visual Studio, no projeto SimulatedDevice, adicione o seguinte método à classe SimulatedDevice.

     private static async void ReceiveC2dAsync()
     {
         Console.WriteLine("\nReceiving cloud to device messages from service");
         while (true)
         {
             Message receivedMessage = await s_deviceClient.ReceiveAsync();
             if (receivedMessage == null) continue;
    
             Console.ForegroundColor = ConsoleColor.Yellow;
             Console.WriteLine("Received message: {0}", 
             Encoding.ASCII.GetString(receivedMessage.GetBytes()));
             Console.ResetColor();
    
             await s_deviceClient.CompleteAsync(receivedMessage);
         }
     }
    
  2. Adicione o seguinte método no método principal , imediatamente antes da Console.ReadLine() linha:

    ReceiveC2dAsync();
    

O ReceiveAsync método devolve assincronamente a mensagem recebida no momento em que é recebida pelo dispositivo. Retorna nulo após um período de tempo especificado. Neste exemplo, é utilizado o padrão de um minuto. Quando a aplicação recebe um nulo, deve continuar a aguardar novas mensagens. Esta exigência é a razão da if (receivedMessage == null) continue linha.

A chamada para CompleteAsync() notificar Hub IoT que a mensagem foi processada com sucesso e que a mensagem pode ser removida com segurança da fila do dispositivo. O dispositivo deve chamar este método quando o seu processamento estiver concluído com sucesso, independentemente do protocolo que está a utilizar.

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

  • Abandone uma mensagem, o que resulta em Hub IoT a retenção da mensagem na fila do dispositivo para consumo futuro.
  • Rejeite uma mensagem que remova permanentemente a mensagem da fila do dispositivo.

Se acontecer algo que impeça o dispositivo de completar, abandonar ou rejeitar a mensagem, Hub IoT irá, após um período de tempo fixo, fazer fila para a entrega novamente. Por este motivo, a lógica de processamento de mensagens na aplicação do dispositivo deve ser idempotente, de modo que receber a mesma mensagem várias vezes produz o mesmo resultado.

Para obter informações mais detalhadas sobre como Hub IoT processa mensagens nuvem-dispositivo, incluindo detalhes do ciclo de vida da mensagem nuvem-para-dispositivo, consulte Enviar mensagens cloud-to-device a partir de um hub IoT.

Nota

Ao utilizar HTTPS em vez de MQTT ou AMQP como transporte, o ReceiveAsync método regressa imediatamente. O padrão suportado para mensagens nuvem-a-dispositivo com HTTPS é dispositivos intermitentemente ligados que verificam mensagens com pouca frequência (um mínimo de cada 25 minutos). A emissão de mais HTTPS resulta em Hub IoT a estrangular os pedidos. Para obter mais informações sobre as diferenças entre suporte MQTT, AMQP e HTTPS, consulte a orientação de comunicações Cloud-to-device e Escolha um protocolo de comunicação.

Obtenha a cadeia de ligação do hub IoT

Neste artigo, cria-se um serviço back-end para enviar mensagens cloud-to-device através do hub IoT que criou em Enviar por email o artigo Telemetria para um hub IoT. Para enviar mensagens nuvem-para-dispositivo, o seu serviço necessita da permissão de ligação de serviço . Por padrão, cada Hub IoT é criado com uma política de acesso partilhado chamada 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:

  1. No portal do Azure, selecione grupos de recursos. Selecione o grupo de recursos onde o seu hub está localizado e, em seguida, selecione o seu hub na lista de recursos.

  2. No painel do lado esquerdo do seu hub IoT, selecione políticas de acesso compartilhados.

  3. Na lista de políticas, selecione a política de serviços .

  4. Nas teclas de acesso partilhadas, selecione o ícone de cópia para a cadeia de ligação primária e guarde o valor.

Screenshot that shows how to retrieve the connection string

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

Envie uma mensagem nuvem-a-dispositivo

Nesta secção, cria-se uma aplicação de consola .NET que envia mensagens nuvem-para-dispositivo para a aplicação do dispositivo simulado.

  1. Na solução de Visual Studio atual, selecione FileNew>> Project. In Create a new project, selecione Console App (.NET Framework)e, em seguida, selecione Next.

  2. Nomeie o projeto SendCloudToDevice. Em Solução, selecione Adicionar à solução e aceitar a versão mais recente do .NET Framework. Selecione Create (Criar) para criar o projeto.

    Configure a new project in Visual Studio

  3. Em Explorador de Soluções, clique com o botão direito no novo projeto e, em seguida, selecione Gerir Pacotes NuGet.

  4. Em Gerir pacotes NuGet, selecione Procurar e, em seguida, procurar e selecionar dispositivos Microsoft.Azure.. Selecione Instalar.

    Este passo descarrega, instala e adiciona uma referência ao pacote SDK NuGet do serviço Azure IoT.

  5. Adicione a seguinte using declaração no topo do ficheiro .cs Programa .

    using Microsoft.Azure.Devices;
    
  6. Adicione os seguintes campos à classe Programa. Substitua o {iot hub connection string} valor do espaço reservado pela cadeia de ligação do hub IoT que notou anteriormente na cadeia de ligação do hub IoT. Substitua o {device id} valor do espaço reservado pelo ID do dispositivo que adicionou na telemetria Enviar telemetria de um dispositivo para um arranque rápido do hub IoT .

    static ServiceClient serviceClient;
    static string connectionString = "{iot hub connection string}";
    static string targetDevice = "{device id}";
    
  7. Adicione o seguinte método à classe Programa para enviar uma mensagem ao seu dispositivo.

    private async static Task SendCloudToDeviceMessageAsync()
    {
         var commandMessage = new
          Message(Encoding.ASCII.GetBytes("Cloud to device message."));
         await serviceClient.SendAsync(targetDevice, commandMessage);
    }
    
  8. Por último, adicione as seguintes linhas ao método Principal .

    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();
    
  9. No Solutions Explorer, clique com o botão direito na sua solução e selecione set StartUp Projects.

  10. Em Propriedades>ComunsStartup Project, selecione vários projetos de startups e, em seguida, selecione a ação Iniciar para SimulatedDevice e SendCloudToDevice. Selecione OK para guardar as alterações.

  11. Prima F5. Ambas as aplicações devem começar. Selecione a janela SendCloudToDevice e prima Enter. Deverá ver a mensagem a ser recebida pela aplicação do dispositivo.

    Device app receiving message

Receber feedback de entrega

É possível solicitar reconhecimentos de entrega (ou expiração) de Hub IoT para cada mensagem nuvem-dispositivo. Esta opção permite que a solução recue para informar facilmente a lógica de retíduo ou compensação. Para obter mais informações sobre o feedback nuvem-a-dispositivo, consulte mensagens D2C e C2D com Hub IoT.

Nesta secção, modifica a aplicação SendCloudToDevice para solicitar feedback e recebe-a do hub IoT.

  1. Em 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);
         }
     }
    

    Note que este padrão de receção é o mesmo usado para receber mensagens nuvem-dispositivo da aplicação do dispositivo.

  2. Adicione a seguinte linha no método Principal , logo a seguir serviceClient = ServiceClient.CreateFromConnectionString(connectionString).

    ReceiveFeedbackAsync();
    
  3. Para solicitar feedback para a entrega da sua mensagem nuvem-para-dispositivo, tem de especificar uma propriedade no método SendCloudToDeviceMessageAsync . Adicione a seguinte linha, logo após a var commandMessage = new Message(...); linha.

    commandMessage.Ack = DeliveryAcknowledgement.Full;
    
  4. Executar as aplicações pressionando F5. Devia ver ambas as aplicações a começar. Selecione a janela SendCloudToDevice e prima Enter. Deverá ver a mensagem a ser recebida pela aplicação do dispositivo e, passados alguns segundos, a mensagem de feedback recebida pela sua aplicação SendCloudToDevice .

    Device app receiving message and service app receiving feedback

Nota

Para simplificar, este tutorial não implementa nenhuma política de retenção. No código de produção, deve implementar políticas de retrocesso, tais como o backoff exponencial, como sugerido no tratamento de falhas transitórias.

Passos seguintes

Neste modo de fazer, aprendeu a enviar e a receber mensagens cloud-to-device.

Para saber mais sobre o desenvolvimento de soluções com Hub IoT, consulte o guia de desenvolvimento Hub IoT.