Tutorial: Utilizar melhoramentos de mensagens Hub IoT do Azure

Os melhoramentos de mensagens são a capacidade de Hub IoT do Azure para carimbar mensagens com informações adicionais antes de as mensagens serem enviadas para o ponto final designado. Um dos motivos para utilizar melhoramentos de mensagens é incluir dados que podem ser utilizados para simplificar o processamento a jusante. Por exemplo, melhorar as mensagens do dispositivo com uma etiqueta de dispositivo duplo pode reduzir a carga nos clientes para efetuar chamadas à API de dispositivos duplos para obter estas informações. Para obter mais informações, veja Descrição geral dos melhoramentos de mensagens.

Na primeira parte deste tutorial, viu como criar pontos finais personalizados e encaminhar mensagens para outros serviços do Azure. Neste tutorial, verá como criar e configurar os recursos adicionais necessários para testar os melhoramentos de mensagens para um hub IoT. Os recursos incluem um segundo contentor de armazenamento para uma conta de armazenamento existente (criada na primeira parte do tutorial) para armazenar as mensagens melhoradas e uma rota de mensagens para as enviar para lá. Depois de concluídas as configurações do encaminhamento de mensagens e melhoramentos de mensagens, utilize uma aplicação para enviar mensagens para o hub IoT. Em seguida, o hub encaminha-os para ambos os contentores de armazenamento. Apenas as mensagens enviadas para o ponto final do contentor de armazenamento melhorado são melhoradas.

Neste tutorial, vai realizar as seguintes tarefas:

• Crie um segundo contentor na sua conta de armazenamento.
• Crie outro ponto final personalizado e encaminhe mensagens para o mesmo a partir do hub IoT.
• Configurar melhoramentos de mensagens que são encaminhados para o novo ponto final.
• Execute uma aplicação que simula um dispositivo IoT a enviar mensagens para o hub.
• Veja os resultados e verifique se os melhoramentos das mensagens estão a ser 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.

• Tem de ter concluído o Tutorial: Enviar dados do dispositivo para o Armazenamento do Microsoft Azure com Hub IoT encaminhamento de mensagens e manter os recursos que criou para o mesmo.

• Certifique-se de que a porta 8883 está aberta na firewall. O exemplo de dispositivo neste tutorial utiliza o protocolo MQTT, que comunica através da porta 8883. Esta porta pode ser bloqueada em alguns ambientes de rede empresarial e educacional. Para obter mais informações e formas de contornar este problema, veja Ligar ao Hub IoT (MQTT).

Portal do Azure

Não existem outros pré-requisitos para a portal do Azure.

CLI do Azure

• Utilize o ambiente bash no Azure Cloud Shell. Para obter mais informações, veja Início Rápido do 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, veja Como executar a CLI do Azure num contentor 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 início de sessão, veja Iniciar sessão com a CLI do Azure.

  • Quando lhe for pedido, 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.

Criar um segundo contentor na sua conta de armazenamento

Na primeira parte deste tutorial, criou uma conta de armazenamento e um contentor para mensagens encaminhadas. Agora, deve criar um segundo contentor para mensagens melhoradas.

Portal do Azure

1. Na portal do Azure, procure Contas de armazenamento.

2. Selecione a conta que criou anteriormente.

3. No menu da conta de armazenamento, selecione Contentores na secção Armazenamento de dados .

4. Selecione Contentor para criar o novo contentor.

   

5. Atribua um nome ao contentor enrichede selecione Criar.

CLI do Azure

Dica

Muitos dos comandos da CLI utilizados ao longo deste tutorial utilizam os mesmos parâmetros. Para sua comodidade, temos de definir variáveis locais que podem ser chamadas conforme necessário. Certifique-se de que executa todos os comandos na mesma sessão ou terá de redefinir as variáveis.

Os valores para estas variáveis devem ser para os mesmos recursos que utilizou na primeira parte deste tutorial.

1. Defina as variáveis para o hub IoT, a conta de armazenamento e o contentor.

   GROUP_NAME: substitua este marcador de posição pelo nome do grupo de recursos que contém o hub IoT.

   IOTHUB_NAME: substitua este marcador de posição pelo nome do seu hub IoT.

   DEVICE_ID: substitua este marcador de posição pelo ID do seu dispositivo.

   STORAGE_NAME: substitua este marcador de posição pelo nome da sua conta de armazenamento.

   Neste tutorial, o valor da containerName variável deve ser melhorado.

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

2. Utilize o comando az storage container create para adicionar o contentor à sua conta de armazenamento.

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

Encaminhar mensagens para um segundo ponto final

Crie um segundo ponto final e encaminhe para as mensagens melhoradas.

Portal do Azure

1. Na portal do Azure, aceda ao seu hub IoT.

2. No menu de recursos, em Definições do hub, selecione Encaminhamento de mensagens e, em seguida, selecione Adicionar.

   

3. No separador Ponto Final , crie um ponto final de Armazenamento ao fornecer as seguintes informações:

   Parâmetro	Valor
   Tipo de ponto final	Selecione Armazenamento.
   Nome do ponto final	Introduza ContosoStorageEndpointEnriched.
   Contentor de Armazenamento do Azure	Selecione Escolher um contentor. Siga as instruções para selecionar a conta de armazenamento e o contentor melhorado que criou na secção anterior.
   Encoding (Codificação)	Selecione JSON. Se este campo estiver desativado, a região da conta de armazenamento não suportará JSON. Nesse caso, continue com o AVRO predefinido.

   

4. Aceite os valores predefinidos para o resto dos parâmetros e selecione Criar + seguinte.

5. Continue a criar a nova rota, agora que adicionou o ponto final de armazenamento. Forneça as seguintes informações para a nova rota:

   Parâmetro	Valor
   Nome	ContosoStorageRouteEnriched
   Origem de dados	Verifique se as Mensagens de Telemetria do Dispositivo estão selecionadas na lista pendente.
   Ativar rota	Verifique se este campo está definido como enabled.
   Consulta de encaminhamento	Introduza level="storage" como cadeia de consulta.

   

6. Selecione Criar + adicionar melhoramentos.

CLI do Azure

1. Configure as variáveis para os comandos de ponto final e rota para utilizar os valores ContosoStorageEndpointEnriched e ContosoStorageRouteEnriched, respetivamente.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Utilize o comando az iot hub routing-endpoint create para criar um ponto final personalizado que aponte para o contentor de armazenamento que criou na secçã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. Utilize o comando az iot hub route create para criar uma rota que transmita qualquer mensagem para level=storage o ponto final do contentor 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"'
   

Adicionar melhoramento de mensagens ao novo ponto final

Crie três melhoramentos de mensagens que serão encaminhados para o contentor de armazenamento melhorado .

Portal do Azure

1. No separador Melhoramento do assistente Adicionar uma rota , adicione três melhoramentos de mensagens para as mensagens que vão para o ponto final do contentor de armazenamento denominado enriched.

   Adicione estes valores como melhoramentos de mensagens para o ponto final ContosoStorageEndpointEnriched:

   Name	Valor
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (pressupõe que o dispositivo duplo tem uma etiqueta de localização)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   Quando tiver terminado, os seus melhoramentos deverão ter um aspeto semelhante a esta imagem:

   

2. Selecione Adicionar para adicionar os melhoramentos de mensagens.

CLI do Azure

Faça três chamadas para o comando az iot hub message-enrichment create para adicionar melhoramentos de mensagens à rota que vai para o ponto final 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 tem melhoramentos de mensagens configurados para todas as mensagens encaminhadas para o ponto final que criou para mensagens melhoradas. Se não quiser adicionar uma etiqueta de localização ao dispositivo duplo, pode avançar para a secção Melhoramentos de mensagens de teste para continuar o tutorial.

Adicionar a etiqueta de localização ao dispositivo duplo

Um dos melhoramentos de mensagens configurados no hub IoT especifica uma chave de DeviceLocation com o respetivo valor determinado pelo seguinte caminho do dispositivo duplo: $twin.tags.location. Se o dispositivo duplo não tiver uma etiqueta de localização, o caminho duplo, $twin.tags.location, será carimbado como uma cadeia para a chave DeviceLocation nos melhoramentos de mensagens.

Siga estes passos para adicionar uma etiqueta de localização ao duplo do dispositivo:

Portal do Azure

1. Navegue para o seu hub IoT no portal do Azure.

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

3. Selecione o separador Dispositivo duplo na parte superior da página do dispositivo e adicione a seguinte linha imediatamente antes da chaveta de fecho na parte inferior do dispositivo duplo. Em seguida, selecione Guardar.

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

   

CLI do Azure

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

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

Dica

Aguarde cerca de cinco minutos antes de avançar para a secção seguinte. Pode demorar até esse tempo para que as atualizações do dispositivo duplo sejam refletidas nos valores de melhoramento de mensagens.

Para saber mais sobre como os caminhos dos dispositivos duplos são processados com melhoramentos de mensagens, veja Limitações de melhoramento de mensagens. Para saber mais sobre dispositivos duplos, consulte Compreender e utilizar dispositivos duplos no Hub IoT.

Testar melhoramentos de mensagens

Agora que os melhoramentos de mensagens estão configurados para o ponto final ContosoStorageEndpointEnriched , execute a aplicação de dispositivo simulado para enviar mensagens para o hub IoT. Neste momento, o encaminhamento de mensagens foi configurado da seguinte forma:

• As mensagens encaminhadas para o ponto final de armazenamento que criou na primeira parte do tutorial não serão enriquecidas e serão armazenadas no contentor de armazenamento que criou nessa altura.

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

Se ainda não estiver a executar a aplicação de consola SimulatedDevice na primeira parte deste tutorial, execute-a novamente:

Dica

Se estiver a seguir os passos da CLI do Azure para este tutorial, execute o código de exemplo numa sessão separada. Dessa forma, pode permitir que o código de exemplo continue em execução enquanto segue os restantes passos da CLI.

1. Na pasta de exemplo, navegue para a /iot-hub/Tutorials/Routing/SimulatedDevice/ pasta .

2. As definições de variáveis que atualizou antes ainda devem ser válidas, mas, caso contrário, edite-as no Program.cs ficheiro:

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

      • s_myDeviceId: o ID do dispositivo que atribuiu ao registar o dispositivo no seu hub IoT.
      • s_iotHubUri: o nome do anfitrião 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 sair da aplicação de consola para ser executada durante alguns minutos, veja os dados:

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

2. Selecione Browser de armazenamento no menu de navegação. Selecione Contentores de blobs para ver os dois contentores que criou ao longo destes tutoriais.

   

As mensagens no contentor denominado enriched têm os melhoramentos de mensagens incluídos nas mensagens. As mensagens no contentor que criou anteriormente têm as mensagens não processadas sem melhoramentos. Desagregar o contentor melhorado até chegar à parte inferior e, em seguida, abrir o ficheiro de mensagens mais recente. Em seguida, faça o mesmo para o outro contentor para verificar se um é melhorado e um não é.

Quando observar as mensagens que foram melhoradas, deverá ver "myIotHub" com o nome do hub, a localização e o ID do cliente, da seguinte forma:

{
  "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 os recursos

Para remover todos os recursos que criou em ambas as partes deste tutorial, elimine o grupo de recursos. Esta ação também elimina todos os recursos contidos no grupo. Se não quiser eliminar todo o grupo de recursos, pode selecionar recursos individuais no mesmo para eliminar.

Portal do Azure

1. No portal do Azure, navegue para o grupo de recursos que contém o hub IoT e a conta de armazenamento deste tutorial.
2. Reveja todos os recursos que estão no grupo de recursos para determinar quais pretende limpar.
   • Se quiser eliminar todo o recurso, selecione Eliminar grupo de recursos.
   • Se quiser eliminar apenas determinado recurso, utilize as caixas de verificação junto a cada nome de recurso para selecionar as que pretende eliminar. Em seguida, selecione Eliminar.

CLI do Azure

1. Utilize o comando az resource list para ver todos os recursos no seu grupo de recursos.

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

2. Reveja todos os recursos que estão no grupo de recursos para determinar quais pretende limpar.

   • Se quiser eliminar todos os recursos, utilize o comando az group delete .

     az group delete --name $resourceGroup
     

   • Se apenas quiser eliminar determinados recursos, utilize o comando az resource delete . Por exemplo:

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

Passos seguintes

Neste tutorial, configurou e testou melhoramentos de mensagens para Hub IoT mensagens à medida que são encaminhadas para um ponto final.

Para obter mais informações sobre melhoramentos de mensagens, veja Descrição geral dos melhoramentos de mensagens.

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

Tutorial: Configurar e utilizar métricas e registos com um hub IoT