Tutorial: Como usar os enriquecimentos de mensagens do Hub IoT do Azure

O enriquecimento de mensagens é a capacidade do Hub IoT do Azure de carimbar mensagens com informações adicionais antes que elas sejam enviadas para o ponto de extremidade designado. Uma razão para usar o enriquecimento de mensagens é incluir dados que podem ser usados para simplificar o processamento a jusante. Por exemplo, enriquecer mensagens de dispositivo com uma tag de gémeo de dispositivo pode reduzir a carga sobre os clientes ao fazerem chamadas de API de gémeo de dispositivo para obter essas informações. Para obter mais informações, consulte Visão geral do enriquecimento 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 o enriquecimento 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 armazenar as mensagens enriquecidas e uma rota de mensagem para enviá-las para lá. Depois que as configurações para o roteamento de mensagens e enriquecimento de mensagens forem concluídas, você usará um aplicativo para enviar mensagens para o hub IoT. Em seguida, o hub os encaminha para ambos os contêineres de armazenamento. Somente as mensagens enviadas para o ponto de extremidade do contentor de armazenamento enriquecido são enriquecidas.

Neste tutorial, vai realizar as seguintes tarefas:

• Crie um segundo contêiner em sua conta de armazenamento.
• Crie outro ponto de extremidade personalizado e roteie mensagens para ele a partir do hub IoT.
• Configure enriquecimentos de mensagens que são encaminhados para o novo endpoint.
• Execute um aplicativo que simule um dispositivo IoT enviando mensagens para o hub.
• Exiba os resultados e verifique se os enriquecimentos de mensagem estão sendo aplicados às mensagens de destino.

Pré-requisitos

• Precisa de uma subscrição do Azure. Se não tiver uma subscrição 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 Azure usando o roteamento de mensagens do Hub IoT e mantido os recursos criados para ele.

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

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 mais informações, veja Get started with 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 Autenticar no Azure usando a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a 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.

Criar 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.

Portal do Azure

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

2. Selecione a conta que criou 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 enrichede selecione Criar.

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.

Os valores para essas 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 este espaço reservado pelo nome do grupo de recursos que contém o hub IoT.

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

   DEVICE_ID: Substitua este marcador de posição pelo ID do 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 o comando az storage container create para adicionar o contêiner à sua conta de armazenamento.

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

Encaminhar mensagens para um segundo endpoint

Crie uma segunda interface e rota para 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 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 para soluções > de IoT Segurança na nuvem.

Portal do Azure

1. No portal Azure, vá para o 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	Valor
   Tipo de ponto final	Selecione Armazenamento.
   Nome do ponto final	Introduza ContosoStorageEndpointEnriched.
   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 enriquecido que você criou na seção anterior.
   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. Continue a criar a nova rota, agora que adicionaste o endpoint de armazenamento. Forneça as seguintes informações para a nova rota:

   Parâmetro	Valor
   Nome	ContosoStorageRouteEnriquecido
   Origem de dados	Verifique se Mensagens de Telemetria de Dispositivo está selecionado na lista suspensa.
   Ativar rota	Verifique se este 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. Utilize o comando az iot hub message-endpoint create para criar um ponto de extremidade personalizado que aponte para o contentor de armazenamento criado 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 message-route create para criar uma rota que passe qualquer mensagem onde level=storage para o ponto de extremidade do contentor 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"'
   

Adicione enriquecimento de mensagem ao novo ponto de extremidade

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

Portal do Azure

1. Na guia "Enriquecimento" do assistente "Adicionar uma rota", adicione três enriquecimentos de mensagem para as mensagens que vão para o endpoint do contentor de armazenamento chamado enriquecido.

   Adicione estes valores como enriquecimentos de mensagens para o ponto de extremidade ContosoStorageEndpointEnriched.

   Nome	Valor
   myIotHub	$hubname
   Localização do dispositivo	$twin.tags.location (assume que o gémeo do dispositivo tem uma etiqueta de localização)
   ID do cliente	6ce345b8-1e4a-411e-9398-d34587459a3a

   Quando terminar, os seus enriquecimentos deverão ser semelhantes a esta imagem:

   

2. Selecione Adicionar para adicionar o enriquecimento da mensagem.

CLI do Azure

Faça três chamadas para o comando az iot hub message-enrichment create para adicionar enriquecimentos de mensagens à 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 tens o enriquecimento de mensagens definido para todas as mensagens redirecionadas para o ponto de extremidade que criaste para mensagens enriquecidas. Se não quiser adicionar uma etiqueta de localização ao dispositivo gemelar, pode saltar para a secção Enriquecimento de mensagens para continuar o tutorial.

Adicionar etiqueta de localização ao gémeo do dispositivo

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

Siga estes passos para adicionar uma etiqueta de localização ao gémeo do seu dispositivo:

Portal do Azure

1. Navegue até seu hub IoT no portal do Azure.

2. Selecione Dispositivos no menu de navegação do hub IoT e, em seguida, selecione o dispositivo.

3. Selecione o separador Gêmeo de Dispositivo no topo da página do dispositivo e adicione a seguinte linha logo antes da chave de encerramento na parte inferior do Gêmeo de Dispositivo. Em seguida, selecione Guardar.

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

   

CLI do Azure

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

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

Gorjeta

Aguarde cerca de cinco minutos antes de continuar para a próxima seção. Pode levar até esse tempo para que as atualizações do gêmeo do dispositivo sejam refletidas nos valores de enriquecimento da mensagem.

Para saber mais sobre como os caminhos gêmeos de dispositivo são tratados com enriquecimento de mensagens, consulte Limitações de enriquecimento de mensagens. Para saber mais sobre gêmeos de dispositivo, consulte Compreender e usar gêmeos de dispositivo no Hub IoT.

Enriquecimento de mensagens de teste

Agora que os enriquecimentos de mensagens estão configurados para o ContosoStorageEndpointEnriquecido, execute o aplicativo de dispositivo simulado para enviar mensagens para o IoT Hub. Neste ponto, o roteamento de mensagens foi configurado da seguinte maneira:

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

• As mensagens encaminhadas para o ponto de extremidade de armazenamento ContosoStorageEndpointEnriched serão enriquecidas e armazenadas no contentor de armazenamento enriched.

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

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

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

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

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

   2. Guarde e feche o ficheiro.

3. Execute o código de exemplo:

   dotnet run
   

Depois de deixar o aplicativo de console para ser executado por alguns minutos, visualize os dados:

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

   

As mensagens no contêiner chamado enriquecido têm os enriquecimentos de mensagem incluídos nas mensagens. As mensagens no contentor que criou anteriormente são mensagens sem processamento, sem qualquer enriquecimento. Analise detalhadamente o contêiner enriquecido até chegar à parte inferior e, em seguida, abra o arquivo de mensagem mais recente. Em seguida, faça o mesmo para o outro recipiente para verificar se um está enriquecido e outro não.

Quando olhas para as mensagens que foram enriquecidas, deverás ver "myIotHub" com o nome do hub, a localização e o ID do cliente, tal como isto:

{
  "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 criados em ambas as partes deste tutorial, exclua o grupo de recursos. Esta ação também elimina todos os recursos contidos no grupo. Se não quiser excluir todo o grupo de recursos, selecione recursos individuais para excluir.

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, configuraste e testaste enriquecimentos de mensagens para mensagens do Hub IoT à medida que são encaminhadas para um destino.

Para obter mais informações sobre enriquecimento de mensagens, consulte Visão geral de enriquecimento de mensagens.

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

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