Tutorial: Enviar dados de dispositivo para o Armazenamento do Azure usando o roteamento de mensagens do Hub IoT

Use o roteamento de mensagens no Hub IoT do Azure para enviar dados de telemetria de seus dispositivos IoT para serviços do Azure, como armazenamento de blobs, filas do Service Bus, tópicos do Service Bus e Hubs de eventos. Cada hub IoT tem um ponto de extremidade interno padrão que é compatível com Hubs de Eventos. Você também pode criar pontos de extremidade personalizados e rotear mensagens para outros serviços do Azure definindo consultas de roteamento. Cada mensagem que chega ao hub IoT é roteada para todos os pontos de extremidade cujas consultas de roteamento correspondem. Se uma mensagem não corresponder a nenhuma das consultas de roteamento definidas, ela será roteada para o ponto de extremidade padrão.

Neste tutorial, vai realizar as seguintes tarefas:

• Crie um hub IoT e envie mensagens de dispositivo para ele.
• Criar uma conta de armazenamento.
• Crie um ponto de extremidade personalizado para a conta de armazenamento e roteie mensagens para ela a partir do hub IoT.
• Exiba mensagens do dispositivo no blob da conta de armazenamento.

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 em sua assinatura do Azure. Se você ainda não tiver um hub, siga as etapas em Criar um hub IoT.

• Este tutorial usa código de exemplo do SDK do Azure IoT para C#.

  • Baixe ou clone o repositório SDK para sua máquina de desenvolvimento.
  • Tenha o .NET Core 3.0.0 ou superior em sua máquina de desenvolvimento. Verifique sua versão executando dotnet --version e baixando o .NET , se necessário.

• Verifique se a porta 8883 está aberta no firewall. O exemplo neste tutorial usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

• Opcionalmente, instale o Azure IoT Explorer. Esta ferramenta ajuda-o a observar as mensagens à medida que chegam ao seu hub IoT. Este artigo usa o Azure IoT Explorer.

Portal do Azure

Não há outros pré-requisitos para o portal do Azure.

CLI do Azure

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

  • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Registrar um dispositivo e enviar mensagens para o Hub IoT

Registre um novo dispositivo em seu hub IoT.

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

Portal do Azure

1. Entre no portal do Azure e navegue até seu hub IoT.

2. Selecione Dispositivos na seção Gerenciamento de dispositivos do menu.

3. Selecione Adicionar dispositivo.

   

4. Forneça um ID de dispositivo e selecione Salvar.

5. O novo dispositivo deve estar na lista de dispositivos agora. Se não estiver, atualize a página. Selecione o ID do dispositivo para abrir a página de detalhes do dispositivo.

6. Copie uma das chaves do dispositivo e salve-a. Você usará esse valor para configurar o código de exemplo que gera mensagens simuladas de telemetria de dispositivo.

   

CLI do Azure

Gorjeta

Muitos dos comandos da CLI usados ao longo deste tutorial usam os mesmos parâmetros. Para sua conveniência, temos que definir variáveis locais que podem ser chamadas conforme necessário. Certifique-se de executar todos os comandos na mesma sessão, ou então você terá que redefinir as variáveis.

1. Defina variáveis para seu hub e dispositivo IoT.

   IOTHUB_NAME: Substitua este espaço reservado pelo nome do seu hub IoT.

   DEVICE_NAME: Substitua este espaço reservado por qualquer nome que você queira usar para o dispositivo neste tutorial.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. Execute o comando az iot hub device-identity create no shell da CLI. Este comando cria a identidade do dispositivo.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. Na saída device-identity, copie o valor primaryKey sem as aspas ao redor e salve-o. Você usará esse valor para configurar o código de exemplo que gera mensagens simuladas de telemetria de dispositivo.

Agora que você tem um ID e uma chave de dispositivo, use o código de exemplo para começar a enviar mensagens de telemetria de dispositivo para o Hub IoT.

Gorjeta

Se você estiver seguindo as etapas da CLI do Azure para este tutorial, execute o código de exemplo em uma sessão separada. Dessa forma, você pode permitir que o código de exemplo continue em execução enquanto segue o restante das etapas da CLI.

1. Se você não fez parte dos pré-requisitos, baixe ou clone o repositório do SDK do Azure IoT para C# do GitHub agora.

2. Na pasta onde você baixou ou clonou o SDK, navegue até a azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample pasta.

3. Instale o Azure IoT C# SDK e as dependências necessárias, HubRoutingSample.csproj conforme especificado no arquivo:

   dotnet restore
   

4. Em um editor de sua escolha, abra o Parameters.cs arquivo. Este arquivo mostra os parâmetros que são suportados pelo exemplo. Somente o PrimaryConnectionString parâmetro será usado neste artigo ao executar o exemplo. Revise o código neste arquivo. Não são necessárias alterações.

5. Crie e execute o código de exemplo usando o seguinte comando:

   Substitua <myDevicePrimaryConnectionString> pela cadeia de conexão principal do dispositivo no hub IoT.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Você deve começar a ver as mensagens impressas na saída à medida que são enviadas para o Hub IoT. Deixe este programa em execução durante o tutorial.

Configurar o IoT Explorer para exibir mensagens

Configure o IoT Explorer para se conectar ao seu hub IoT e ler mensagens à medida que elas chegam ao ponto de extremidade interno.

Primeiro, recupere a cadeia de conexão para seu hub IoT.

Portal do Azure

1. No portal do Azure, navegue para o seu hub IoT.

2. Selecione Políticas de acesso compartilhado na seção Configurações de segurança do menu.

3. Selecione a política iothubowner .

   

4. Copie a cadeia de conexão primária.

   

CLI do Azure

1. Execute o comando az iot hub connection-string show :

   az iot hub connection-string show --hub-name $hubName
   

2. Copie a cadeia de conexão sem as aspas ao redor.

Agora, use essa cadeia de conexão para configurar o IoT Explorer para seu hub IoT.

1. Abra o IoT Explorer em sua máquina de desenvolvimento.

2. Selecione Adicionar ligação.

   

3. Cole a cadeia de conexão do hub na caixa de texto.

4. Selecione Guardar.

5. Depois de se conectar ao seu hub IoT, você verá uma lista de dispositivos. Selecione o ID do dispositivo que você criou para este tutorial.

6. Selecione Telemetria.

7. Com o dispositivo ainda em execução, selecione Iniciar. Se o dispositivo não estiver em execução, você não verá a telemetria.

   

8. Você deve ver as mensagens que chegam do seu dispositivo, com as mais recentes exibidas na parte superior.

   

   Observe as mensagens recebidas por alguns momentos para verificar se você vê três tipos diferentes de mensagens: normal, de armazenamento e crítica. Depois de ver isso, você pode parar seu dispositivo.

Todas essas mensagens estão chegando ao ponto de extremidade interno padrão para seu hub IoT. Nas próximas seções, vamos criar um ponto de extremidade personalizado e rotear algumas dessas mensagens para o armazenamento com base nas propriedades da mensagem. Essas mensagens deixarão de aparecer no IoT Explorer porque as mensagens só vão para o ponto de extremidade interno quando não corresponderem a nenhuma outra rota no hub IoT.

Configurar o encaminhamento de mensagens

Você vai rotear mensagens para diferentes recursos com base nas propriedades anexadas à mensagem pelo dispositivo simulado. As mensagens que não são roteadas personalizadas são enviadas para o ponto de extremidade padrão (mensagens/eventos).

O aplicativo de exemplo para este tutorial atribui uma propriedade level a cada mensagem enviada ao hub IoT. A cada mensagem é atribuído aleatoriamente um nível normal, de armazenamento ou crítico.

O primeiro passo é configurar o ponto de extremidade para o qual os dados serão roteados. A segunda etapa é configurar a rota de mensagem que usa esse ponto de extremidade. Depois de configurar o roteamento, você pode visualizar pontos de extremidade e rotas de mensagens no portal.

Criar uma conta de armazenamento

Crie uma conta de Armazenamento do Azure e um contêiner dentro dessa conta, que armazenará as mensagens do dispositivo que são roteadas para ela.

Portal do Azure

1. No portal do Azure, procure contas de armazenamento.

2. Selecione Criar.

3. Forneça os seguintes valores para sua conta de armazenamento:

   Parâmetro	Value
   Subscrição	Selecione a mesma assinatura que contém seu hub IoT.
   Grupo de recursos	Selecione o mesmo grupo de recursos que contém seu hub IoT.
   Nome da conta de armazenamento	Forneça um nome globalmente exclusivo para sua conta de armazenamento.
   Desempenho	Aceite o valor Standard padrão.

   

4. Você pode aceitar todos os outros valores padrão selecionando Revisar + criar.

5. Após a conclusão da validação, selecione Criar.

6. Quando a implementação estiver concluída, selecione Ir para recurso.

7. No menu da conta de armazenamento, selecione Contêineres na seção Armazenamento de dados.

8. Selecione + Contêiner para criar um novo contêiner.

   

9. Forneça um nome para seu contêiner e selecione Criar.

CLI do Azure

1. Defina as variáveis para sua conta de armazenamento e contêiner.

   GROUP_NAME: Substitua este espaço reservado pelo nome do grupo de recursos que contém o hub IoT.

   STORAGE_NAME: Substitua este espaço reservado por um nome para sua conta de armazenamento. Os nomes das contas de armazenamento devem ser minúsculos e globalmente exclusivos.

   CONTAINER_NAME: Substitua este espaço reservado por um nome para o contêiner.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. Use o comando az storage account create para criar uma conta de armazenamento v2 de uso geral padrão.

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. Use o az storage container create para adicionar um contêiner à sua conta de armazenamento.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Rota para uma conta de armazenamento

Agora configure o encaminhamento para a conta de armazenamento. Nesta seção, você define um novo ponto de extremidade que aponta para a conta de armazenamento que você criou. Em seguida, crie uma rota que filtre as mensagens em que a propriedade level está definida como armazenamento e encaminhe-as para o ponto de extremidade de armazenamento.

Nota

Os dados podem ser gravados no armazenamento de blob no formato Apache Avro , que é o padrão, ou JSON.

O formato de codificação só pode ser definido no momento em que o ponto de extremidade de armazenamento de blob é configurado. O formato não pode ser alterado para um ponto de extremidade que já tenha sido configurado. Ao usar a codificação JSON, você deve definir o contentType como JSON e o contentEncoding como UTF-8 nas propriedades do sistema de mensagens.

Para obter informações mais detalhadas sobre como usar um ponto de extremidade de armazenamento de blob, consulte as orientações sobre roteamento para armazenamento.

Importante

Este artigo inclui etapas para se conectar a um serviço usando uma assinatura de acesso compartilhado. Esse método de autenticação é conveniente para teste e avaliação, mas autenticar em um serviço com ID do Microsoft Entra ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança na nuvem.

Portal do Azure

1. No portal do Azure, vá para seu hub IoT.

2. No menu de recursos em Configurações do Hub, selecione Roteamento de mensagens e, em seguida, selecione Adicionar.

   

3. Na guia Ponto de extremidade, crie um ponto de extremidade de armazenamento fornecendo as seguintes informações:

   Parâmetro	Value
   Tipo de ponto final	Selecione Armazenamento.
   Nome do ponto final	Forneça um nome exclusivo para esse ponto de extremidade.
   Contêiner de armazenamento do Azure	Selecione Escolher um contêiner. Siga as instruções para selecionar a conta de armazenamento e o contêiner que você criou na seção anterior.
   Encoding (Codificação)	Selecione JSON. Se este campo estiver acinzentado, a região da sua conta de armazenamento não suporta JSON. Nesse caso, continue com o AVRO padrão.

   

4. Aceite os valores padrão para o restante dos parâmetros e selecione Criar + próximo.

5. Na guia Rota, forneça as seguintes informações para criar uma rota que aponte para o ponto de extremidade de armazenamento que você criou:

   Parâmetro	Valor
   Nome	Crie um nome para a sua rota.
   Origem de dados	Verifique se Mensagens de Telemetria de Dispositivo está selecionado na lista suspensa.
   Ativar rota	Verifique se este campo está marcado.
   Consulta de roteamento	Insira level="storage" como a cadeia de caracteres de consulta.

   

6. Selecione Criar + ignorar enriquecimentos.

CLI do Azure

1. Configure as variáveis necessárias para os comandos endpoint e route.

   ENDPOINT_NAME: Forneça um nome para o ponto de extremidade que representa seu contêiner de armazenamento.

   ROUTE_NAME: Forneça um nome para a rota que filtra mensagens para o ponto de extremidade de armazenamento

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. Use o comando az iot hub message-endpoint create para criar um ponto de extremidade personalizado que aponte para o contêiner de armazenamento criado na seção anterior.

   az iot hub message-endpoint create storage-container \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Use o comando az iot hub message-route create para criar uma rota que passe qualquer mensagem para level=storage o ponto de extremidade do contêiner de armazenamento.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Ver mensagens encaminhadas

Depois que a rota for criada no Hub IoT e habilitada, ela começará imediatamente a rotear mensagens que atendam à sua condição de consulta para o ponto de extremidade de armazenamento.

Monitore o ponto de extremidade interno com o IoT Explorer

Retorne à sessão do IoT Explorer em sua máquina de desenvolvimento. Lembre-se de que o IoT Explorer monitora o ponto de extremidade interno para seu hub IoT. Isso significa que agora você deve ver apenas as mensagens que não estão sendo roteadas pela rota personalizada que criamos.

Inicie o exemplo novamente executando o código. Observe as mensagens recebidas por alguns momentos e você só deve ver as mensagens onde level está definido como normal ou critical.

Exibir mensagens no contêiner de armazenamento

Verifique se as mensagens estão chegando no contêiner de armazenamento.

1. No portal do Azure, navegue para a sua conta de armazenamento.

2. Selecione Contêineres na seção Armazenamento de dados do menu.

3. Selecione o contêiner que você criou para este tutorial.

4. Deve haver uma pasta com o nome do seu hub IoT. Analise detalhadamente a estrutura do arquivo até chegar a um arquivo .json .

   

5. Selecione o arquivo JSON e, em seguida, selecione Download para baixar o arquivo JSON. Confirme se o ficheiro contém mensagens do dispositivo com a level propriedade definida como storage.

6. Pare de executar a amostra.

Clean up resources (Limpar recursos)

Se você quiser remover todos os recursos do Azure usados para este tutorial, exclua o grupo de recursos. Esta ação também elimina todos os recursos contidos no grupo. Se você não quiser excluir todo o grupo de recursos, use o portal do Azure para localizar e excluir os recursos individuais.

Se você pretende continuar para o próximo tutorial, mantenha os recursos que você criou aqui.

Portal do Azure

1. No portal do Azure, navegue até o grupo de recursos que contém o hub IoT e a conta de armazenamento para este tutorial.
2. Revise todos os recursos que estão no grupo de recursos para determinar quais você deseja limpar.
   • Se quiser excluir todo o recurso, selecione Excluir grupo de recursos.
   • Se você quiser excluir apenas determinados recursos, use as caixas de seleção ao lado de cada nome de recurso para selecionar os que deseja excluir. Em seguida, selecione Eliminar.

CLI do Azure

1. Use o comando az resource list para exibir todos os recursos do seu grupo de recursos.

   az resource list --resource-group $resourceGroup --output table
   

2. Revise todos os recursos que estão no grupo de recursos para determinar quais você deseja limpar.

   • Se você quiser excluir todos os recursos, use o comando az group delete .

     az group delete --name $resourceGroup
     

   • Se você quiser excluir apenas determinados recursos, use o comando az resource delete . Por exemplo:

     az resource delete --resource-group $resourceGroup --name $storageName
     

Próximos passos

Neste tutorial, você aprendeu como criar um ponto de extremidade personalizado para um recurso do Azure e, em seguida, criar uma rota para enviar mensagens de dispositivo para esse ponto de extremidade. Continue para o próximo tutorial para aprender a enriquecer mensagens com dados extras que podem ser usados para simplificar o processamento downstream

Usar enriquecimento de mensagens do Hub IoT do Azure