Tutorial: Usar os enriquecimentos de mensagens do Hub IoT do Azure

Os enriquecimentos de mensagens são a capacidade do Hub IoT do Azure de aplicar um carimbo de data/hora às mensagens com informações adicionais antes que elas sejam enviadas para o ponto de extremidade designado. Um motivo para usar os enriquecimentos de mensagens é incluir dados que possam ser usados para simplificar o processamento downstream. Por exemplo, enriquecer mensagens do dispositivo com uma marca de dispositivo gêmeo pode reduzir a carga em clientes para fazer chamadas à API do dispositivo gêmeo a fim de obter essas informações. Para obter mais informações, confira Visão geral dos enriquecimentos de mensagens.

Na primeira parte deste tutorial, você viu como criar pontos de extremidade personalizados e rotear mensagens para outros serviços do Azure. Neste tutorial, você verá como criar e configurar os recursos extras necessários para testar os enriquecimentos de mensagens para um hub IoT. Os recursos incluem um segundo contêiner de armazenamento para uma conta de armazenamento existente (criada na primeira parte do tutorial) para manter as mensagens enriquecidas e uma rota de mensagem para enviá-las para lá. Depois que as configurações do roteamento e dos enriquecimentos de mensagens forem concluídas, você usará um aplicativo para enviar mensagens ao hub IoT. Em seguida, o hub roteia-as para os dois contêineres de armazenamento. Somente as mensagens enviadas ao ponto de extremidade do contêiner de armazenamento enriquecido são enriquecidas.

Neste tutorial, você executa as seguintes tarefas:

• Crie um segundo contêiner em sua conta de armazenamento.
• Crie outro ponto de extremidade personalizado e encaminhe mensagens para ele do hub IoT.
• Configure os enriquecimentos de mensagens que são roteados para o novo ponto de extremidade.
• Executar um aplicativo que simula um dispositivo IoT enviando mensagens para o hub.
• Exiba os resultados e verifique se os enriquecimentos de mensagens estão sendo aplicados às mensagens de destino.

Pré-requisitos

• Você precisa ter uma assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• Você deve ter concluído o Tutorial: Enviar dados do dispositivo para o Armazenamento do Microsoft Azure usando o roteamento de mensagens do Hub IoT e mantido os recursos que você criou para ele.

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

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.

Crie um segundo contêiner em sua conta de armazenamento

Na primeira parte deste tutorial, você criou uma conta de armazenamento e um contêiner para mensagens roteadas. Agora você deve criar um segundo contêiner para mensagens enriquecidas.

Azure portal

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

2. Selecione a conta criada anteriormente.

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

4. Selecione Contêiner para criar o novo contêiner.

   

5. Nomeie o contêiner enriched e selecione Criar.

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.

Os valores dessas variáveis devem ser para os mesmos recursos que você usou na primeira parte deste tutorial.

1. Defina as variáveis para seu hub IoT, conta de armazenamento e contêiner.

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

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

   DEVICE_ID: substitua este espaço reservado pelo ID do seu dispositivo.

   STORAGE_NAME: substitua este espaço reservado pelo nome da sua conta de armazenamento.

   Para este tutorial, o valor da containerName variável deve ser enriquecido.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. 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 mensagens para um segundo endpoint

Crie um segundo endpoint e roteie as mensagens enriquecidas.

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 a autenticação em um serviço com o Microsoft Entra ID ou identidades gerenciadas é uma abordagem mais segura. Para saber mais, consulte Melhores Práticas de Segurança > Segurança da Nuvem.

Portal do Azure

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	Insira ContosoStorageEndpointEnriched.
   Contêiner de Armazenamento do Azure	Selecione Escolher um contêiner. Siga os prompts para selecionar a conta de armazenamento e o contêiner enriquecido 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. Agora que você adicionou o ponto de extremidade de armazenamento, continue criando a nova rota. Forneça as seguintes informações para a nova rota:

   Parâmetro	Valor
   Nome	ContosoStorageRouteEnriched
   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á definido como enabled.
   Consulta de roteamento	insira level="storage" como a cadeia de caracteres de consulta.

   

6. Selecione Criar + adicionar enriquecimentos.

CLI do Azure

1. Configure as variáveis para os comandos endpoint e route para usar os valores ContosoStorageEndpointEnriched e ContosoStorageRouteEnriched, respectivamente.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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 message-endpoint create \
     --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 route create para criar uma rota que passe qualquer mensagem em que o level=storage para 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"'
   

Adicionar enriquecimento de mensagens ao novo ponto de extremidade

Crie três enriquecimentos de mensagens que serão roteados para o contêiner de armazenamento enriquecido.

Azure portal

1. Na guia Enriquecimento do assistente Adicionar uma rota, adicione três enriquecimentos de mensagens às mensagens que vão para o ponto de extremidade do contêiner de armazenamento chamado enriquecido.

   Adicione esses valores como enriquecimentos de mensagens para o ponto de extremidade ContosoStorageEndpointEnriched:

   Nome	Valor
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (assume que o dispositivo gêmeo tem uma marca de localização)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   Quando você terminar, os enriquecimentos serão semelhantes a esta imagem:

   

2. Selecione Adicionar para adicionar os enriquecimentos de mensagem.

CLI do Azure

Faça três chamadas para o comando az iot hub message-enrichment create para adicionar enriquecimentos de mensagem à rota que vai para o ponto de extremidade criado anteriormente.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Agora você tem enriquecimentos de mensagens configurados para todas as mensagens roteadas para o endpoint que você criou para mensagens enriquecidas. Se você não quiser adicionar uma etiqueta de localização ao dispositivo gêmeo, pule para a seção Enriquecimentos de mensagens de teste para continuar o tutorial.

Adicionar uma marca de localização ao dispositivo gêmeo

Um dos enriquecimentos de mensagem configurados em seu hub IoT especifica uma chave de DeviceLocation com seu valor determinado pelo seguinte caminho duplo de dispositivo: $twin.tags.location. Se o seu dispositivo gêmeo não tiver uma etiqueta de localização, o caminho gêmeo, $twin.tags.location, será carimbado como uma string para a chave DeviceLocation nos enriquecimentos da mensagem.

Siga estas etapas para adicionar uma etiqueta de localização ao gêmeo do seu dispositivo:

Azure portal

1. Vá ao Hub IoT no portal do Azure.

2. Selecione Dispositivos no menu de navegação do Hub IoT e depois selecione o dispositivo.

3. Selecione a guia Dispositivo gêmeo na parte superior da página do dispositivo e adicione a linha a seguir logo antes da chave de fechamento na parte inferior do dispositivo gêmeo. Em seguida, selecione Salvar.

     , "tags": {"location": "Plant 43"}
   

   

CLI do Azure

Use o comando az iot hub device-twin update para atualizar o dispositivo gêmeo com uma nova chave e valor de tag.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Dica

Aguarde cerca de cinco minutos para continuar na próxima seção. Esse é o tempo máximo necessário para que as atualizações do dispositivo gêmeo sejam refletidas nos valores de enriquecimento de mensagem.

Para saber mais sobre como os caminhos do dispositivo gêmeo são tratados com enriquecimentos de mensagens, confira Limitações de enriquecimentos de mensagens. Para saber mais sobre o conceito de dispositivos gêmeos, confira Compreender e usar dispositivos gêmeos no Hub IoT.

Testar enriquecimentos de mensagens

Agora que os enriquecimentos de mensagens estão configurados para o ponto de extremidade ContosoStorageEndpointEnriched, execute o aplicativo de dispositivo simulado para enviar mensagens para o hub IoT. Neste ponto, o roteamento de mensagens foi configurado da seguinte forma:

• As mensagens roteadas para o ponto de extremidade de armazenamento que você criou na primeira parte do tutorial não serão enriquecidas e serão armazenadas no contêiner de armazenamento que você criou.

• As mensagens roteadas para o ponto de extremidade de armazenamento ContosoStorageEndpointEnriched serão enriquecidas e armazenadas no contêiner de armazenamento enriquecido.

Se você ainda não estiver executando o aplicativo de console SimulatedDevice da primeira parte deste tutorial, execute-o novamente:

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. Na pasta de exemplo, navegue até a pasta /iot-hub/Tutorials/Routing/SimulatedDevice/.

2. As definições de variáveis que você atualizou antes ainda devem ser válidas, mas, se não, edite-as no arquivo Program.cs:

   1. Localize as definições de variável na parte superior da classe Programa. Atualize as seguintes variáveis com suas próprias informações:

      • s_myDeviceId: a ID do dispositivo que você atribuiu ao registrar o dispositivo no hub IoT.
      • s_iotHubUri: o nome do host do hub IoT, que usa o formato IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: a chave primária do dispositivo encontrada nas informações de identidade do dispositivo.

   2. Salve e feche o arquivo.

3. Execute o código de exemplo:

   dotnet run
   

Depois de deixar o aplicativo de console em execução por alguns minutos, visualize os dados:

1. No Portal do Azure, navegue até sua conta de armazenamento.

2. Selecione Navegador de armazenamento no menu de navegação. Selecione contêineres de Blob para ver os dois contêineres que você criou ao longo desses tutoriais.

   

As mensagens do contêiner chamadas enriquecidas têm os enriquecimentos de mensagens incluídos nas mensagens. As mensagens no contêiner que você criou anteriormente têm as mensagens brutas sem enriquecimentos. Faça uma busca detalhada no contêiner enriquecido até chegar ao final e abra o arquivo de mensagem mais recente. Em seguida, faça o mesmo para o outro contêiner para verificar se um é enriquecido e o outro não.

Ao observar as mensagens que foram enriquecidas, você deverá ver "myIotHub" com o nome do hub, o local e o ID do cliente, assim:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Limpar recursos

Para remover todos os recursos que você criou em ambas as partes deste tutorial, exclua o grupo de recursos. Essa ação também exclui todos os recursos contidos no grupo. Se você não quiser excluir todo o grupo de recursos, poderá selecionar recursos individuais para excluir.

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ê configurou e testou enriquecimentos de mensagens para mensagens do Hub IoT à medida que são roteadas para um ponto de extremidade.

Para obter mais informações sobre os enriquecimentos de mensagens, confira Visão geral dos enriquecimentos de mensagens.

Para saber mais sobre o Hub IoT, continue no próximo tutorial.

Tutorial: Configurar e usar métricas e logs com um hub IoT