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 barramento de serviço, tópicos do barramento de serviço e hubs de eventos. Todo o hub IoT tem um ponto de extremidade interno padrão que é compatível com os Hubs de Eventos. Também é possível 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 correspondam. Se uma mensagem não corresponder a nenhuma das consultas de roteamentos definidas, ela será roteada para o ponto de extremidade padrão.

Neste tutorial, você executa as seguintes tarefas:

• Criar um hub IoT e enviar mensagens de dispositivo para ele.
• Criar uma conta de armazenamento.
• Criar um ponto de extremidade personalizado para a conta de armazenamento e rotear mensagens à ela a partir do hub IoT.
• Exibir mensagens de dispositivo no blob da conta de armazenamento.

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.

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

  • Baixe ou clone o repositório do SDK no computador de desenvolvimento.
  • Tenha o .NET Core 3.0.0 ou mais recente no computador de desenvolvimento. Verifique a sua versão executando dotnet --version e Baixe o .NET, se necessário.

• Verifique se a porta 8883 está aberta no firewall. A amostra deste tutorial 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).

• Como opção, instale o Azure IoT Explorer. Essa ferramenta ajuda você a observar as mensagens assim que elas chegam ao hub IoT. Este artigo usa o Azure IoT Explorer.

Azure portal

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, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Registrar um dispositivo e enviar mensagens para o Hub IoT

Registre um novo dispositivo no seu hub IoT.

Azure portal

1. Entre no Portal do Azure e navegue até o Hub IoT.

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

3. Selecione Adicionar dispositivo.

   

4. Forneça uma identidade do dispositivo e selecione Salvar.

5. O novo dispositivo agora deve estar na lista de dispositivos. Caso negativo, atualize a página. Selecione a identidade do dispositivo e abra 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 de telemetria de dispositivo simulado.

   

CLI do Azure

Dica

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

1. Defina as variáveis para o hub IoT e o dispositivo.

   IOTHUB_NAME: substitua esse espaço reservado pelo nome do seu hub IoT.

   DEVICE_NAME: substitua esse 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 seu shell da CLI. Esse comando cria a identidade do dispositivo.

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

3. Na saída da identidade do dispositivo, 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 de telemetria de dispositivo simulado.

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

Dica

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 maneira, você permite que o código de exemplo continue em execução enquanto segue o restante das etapas da CLI.

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

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

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

   dotnet restore
   

4. Em um editor de sua escolha abra o arquivo Parameters.cs. Esse arquivo mostra os parâmetros compatíveis com o exemplo. Somente o parâmetro PrimaryConnectionString será usado neste artigo durante a execução do exemplo. Examine o código deste arquivo. Nenhuma alteração é necessária.

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

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

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Você deve começar a ver as mensagens impressas na saída à medida que elas são enviadas ao 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 hub IoT e ler mensagens à medida que elas chegam ao ponto de extremidade interno.

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

Azure portal

1. No portal do Azure, navegue para o 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.

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

1. Abra o IoT Explorer no computador de desenvolvimento.

2. Selecione Adicionar conexão.

   

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

4. Selecione Save.

5. Depois de se conectar ao hub IoT, você deverá ver uma lista de dispositivos. Selecione a identidade 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ê deverá ver as mensagens que chegam do seu dispositivo, com as mais recentes exibidas na parte superior.

   

   Observe as mensagens de entrada por alguns instantes para verificar se você vê três tipos diferentes de mensagens: normal, armazenamento e crítica. Depois de ver isso, você poderá parar o dispositivo.

Todas essas mensagens estão chegando ao ponto de extremidade interno padrão para o hub IoT. Nas próximas seções, vamos criar um ponto de extremidade personalizado e rotear algumas dessas mensagens para o armazenamento conforme as 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 correspondem a nenhuma outra rota no hub IoT.

Configurar roteamento de mensagens

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

O aplicativo de exemplo para este tutorial atribui uma propriedade de nível a cada mensagem enviada ao hub IoT. Cada mensagem é atribuída aleatoriamente com um nível de normal, armazenamento ou crítica.

A primeira etapa é configurar o ponto de extremidade ao 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, será possível exibir as rotas de mensagem e os pontos de extremidade no portal.

Criar uma conta de armazenamento

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

Azure portal

1. No portal do Azure, pesquise as Contas de armazenamento.

2. Selecione Criar.

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

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

   

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

5. Depois de concluir a validação, selecione Criar.

6. Depois da conclusão da implantação, selecione Ir para o recurso.

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

8. Escolha + Contêiner para criar um contêiner.

   

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

CLI do Azure

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

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

   STORAGE_NAME: substitua esse espaço reservado por um nome para a conta de armazenamento. Os nomes de conta de armazenamento devem conter apenas letras minúsculas e ser globalmente exclusivo.

   CONTAINER_NAME: substitua esse 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 padrão de uso geral v2.

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

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

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

Rotear para uma conta de armazenamento

Agora, configure o roteamento para a conta de armazenamento. Nesta seção, você define um novo ponto de extremidade que aponta para a conta de armazenamento criada. Em seguida, crie uma rota que filtra as mensagens em que a propriedade de nível está definida como armazenamento e roteie-as para o ponto de extremidade de armazenamento.

Observação

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

O formato de codificação pode ser definido somente no momento em que o ponto de extremidade de armazenamento de blobs é configurado. O formato não pode ser alterado para um ponto de extremidade que já foi 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 mensagem.

Para obter informações mais detalhadas sobre como usar um ponto de extremidade do Armazenamento de Blobs, veja as orientações sobre o roteamento para o armazenamento.

Azure portal

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

2. No menu de recursos, em configurações do Hub, selecione Roteamento de mensagens e então selecione Adicionar.

   

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

   Parâmetro	Valor
   Tipo de ponto de extremidade	Selecione Armazenamento.
   Nome do ponto de extremidade	Forneça um nome exclusivo para esse ponto de extremidade.
   Contêiner de Armazenamento do Azure	Selecione Escolher um contêiner. Siga os prompts para selecionar a conta de armazenamento e o contêiner que você criou na seção anterior.
   Codificação	Selecione JSON. Se esse campo estiver esmaecido, a região da conta de armazenamento não dá suporte a JSON. Nesse caso, continue com o AVRO padrão.

   

4. Aceite os valores padrão para o restante dos parâmetros e selecione Criar + avançar.

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 rota.
   Fonte de dados	Verifique se a opção Mensagens de Telemetria de Dispositivo está selecionada na lista suspensa.
   Habilitar rota	Verifique se esse campo está selecionado.
   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 de ponto de extremidade e de rota.

   ENDPOINT_NAME: forneça um nome para o ponto de extremidade que represente o contêiner de armazenamento.

   ROUTE_NAME: forneça um nome para a rota que filtre mensagens para o ponto de extremidade de armazenamento

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

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

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

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

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

Exibir mensagens roteadas

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

Monitorar o ponto de extremidade interno com o IoT Explorer

Retorne à sessão do IoT Explorer no computador de desenvolvimento. Lembre-se de que o IoT Explorer monitora o ponto de extremidade interno do hub IoT. Isso significa que agora você deverá 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 de entrada por alguns instantes e você só deverá ver mensagens nas quais 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 até 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. Deverá haver uma pasta com o nome do hub IoT. Analise detalhadamente a estrutura do arquivo até chegar a um arquivo .json.

   

5. Selecione o arquivo JSON e clique em Baixar para baixar o arquivo JSON. Confirme se o arquivo contém as mensagens do dispositivo que têm a propriedade level definida como storage.

6. Interrompa a execução do exemplo.

Limpar os recursos

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

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

Azure portal

1. No portal do Azure, navegue até o grupo de recursos que contenha o hub IoT e a conta de armazenamento deste tutorial.
2. Examine todos os recursos que estão no grupo de recursos para determinar quais deles você quer limpar.
   • Se você quiser excluir todos os recursos, selecione Excluir grupo de recursos.
   • Caso queira excluir apenas determinado recurso, use as caixas de seleção ao lado de cada nome de recurso para escolher aqueles que deseja excluir. Em seguida, selecione Excluir.

CLI do Azure

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

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

2. Examine todos os recursos que estão no grupo de recursos para determinar quais deles você quer limpar.

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

     az group delete --name $resourceGroup
     

   • Caso queira excluir apenas determinados recursos, use o comando az resource delete. Por exemplo:

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

Próximas etapas

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

Usar os enriquecimentos de mensagens do Hub IoT do Azure