Partilhar via


Melhoramentos de mensagens para mensagens de Hub IoT dispositivo para cloud

Os melhoramentos de mensagens são a capacidade de um hub IoT 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 de telemetria do dispositivo com uma etiqueta de dispositivo duplo pode reduzir a carga nos clientes para fazer chamadas à API de dispositivo duplo para estas informações.

Fluxo de melhoramentos de mensagens

Um melhoramento de mensagens tem três elementos-chave:

  • Nome ou chave de melhoramento

  • Um valor

  • Um ou mais pontos finais para os quais o melhoramento deve ser aplicado.

A chave é uma cadeia. Uma chave só pode conter carateres alfanuméricos ou estes carateres especiais: hífen (-), caráter de sublinhado (_) e ponto final (.).

O valor pode ser qualquer um dos seguintes exemplos:

  • Qualquer cadeia estática. Não são permitidos valores dinâmicos, como condições, lógica, operações e funções. Por exemplo, se desenvolver uma aplicação SaaS que é utilizada por vários clientes, pode atribuir um identificador a cada cliente e disponibilizar esse identificador na aplicação. Quando a aplicação é executada, Hub IoT irá carimbar as mensagens de telemetria do dispositivo com o identificador do cliente, tornando possível processar as mensagens de forma diferente para cada cliente.

  • O nome do hub IoT a enviar a mensagem. Este valor é $iothubname.

  • Informações do dispositivo duplo, como o respetivo caminho. Os exemplos seriam $twin.tags.field e $twin.tags.latitude.

    Nota

    Neste momento, apenas $iothubname, $twin.tags, $twin.properties.desired e $twin.properties.reported são variáveis suportadas para melhoramento de mensagens. Além disso, apenas os tipos primitivos são suportados para melhoramentos. As mensagens não podem ser melhoradas com tipos de objetos.

Os Melhoramentos de Mensagens são adicionados como propriedades da aplicação às mensagens enviadas para os pontos finais escolhidos.

Aplicar melhoramentos

As mensagens podem ser provenientes de qualquer origem de dados suportada pelo encaminhamento de mensagens Hub IoT, incluindo os seguintes exemplos:

  • telemetria do dispositivo, como temperatura ou pressão
  • notificações de alteração de dispositivo duplo - alterações no dispositivo duplo
  • eventos de ciclo de vida do dispositivo, como quando o dispositivo é criado ou eliminado

Pode adicionar melhoramentos a mensagens que vão para o ponto final incorporado de um hub IoT ou para mensagens que estão a ser encaminhadas para pontos finais personalizados, como o armazenamento de Blobs do Azure, uma fila do Service Bus ou um tópico do Service Bus.

Também pode adicionar melhoramentos às mensagens que estão a ser publicadas no Event Grid ao criar primeiro uma subscrição do Event Grid com o tipo de mensagem de telemetria do dispositivo. Com base nesta subscrição, vamos criar uma rota predefinida no Hub IoT do Azure para a telemetria. Esta rota única pode processar todas as suas subscrições do Event Grid. Em seguida, pode configurar melhoramentos para o ponto final com o separador Melhorar mensagens da secção encaminhamento de mensagens Hub IoT. Para obter informações sobre como reagir a eventos com o Event Grid, veja Hub Iot e Event Grid.

Os melhoramentos são aplicados por ponto final. Se especificar cinco melhoramentos a carimbar para um ponto final específico, todas as mensagens que vão para esse ponto final serão carimbadas com os mesmos cinco melhoramentos.

Os melhoramentos podem ser configurados com os seguintes métodos:

Método Comando
Portal portal do Azure Veja o tutorial de melhoramentos de mensagens
CLI do Azure az iot hub message-enrichment
Azure PowerShell Add-AzIotHubMessageEnrichment

Adicionar melhoramentos de mensagens não adiciona latência ao encaminhamento de mensagens.

Para experimentar melhoramentos de mensagens, veja o tutorial de melhoramentos de mensagens

Limitações

  • Pode adicionar até 10 melhoramentos por hub IoT para esses hubs no escalão padrão ou básico. Para hubs IoT no escalão gratuito, pode adicionar até 2 melhoramentos.

  • Em alguns casos, se estiver a enriquecer uma mensagem com um valor definido como uma etiqueta ou propriedade no dispositivo duplo, o valor será carimbado com o caminho do dispositivo duplo especificado. Por exemplo, se um valor de melhoramento estiver definido como $twin.tags.field, as mensagens serão carimbadas com a cadeia "$twin.tags.field", em vez do valor desse campo do duplo. Este comportamento ocorre nos seguintes casos:

    • O seu hub IoT está no escalão básico. Os hubs IoT de escalão básico não suportam dispositivos duplos.

    • O hub IoT está na camada padrão, mas o caminho do dispositivo duplo utilizado para o valor do melhoramento não existe. Por exemplo, se o valor de melhoramento estiver definido como $twin.tags.location e o dispositivo duplo não tiver uma propriedade de localização em etiquetas, a mensagem será carimbada com a cadeia "$twin.tags.location".

    • O hub IoT está na camada padrão, mas o caminho do dispositivo duplo utilizado para o valor do melhoramento é resolvido para um objeto, em vez de uma propriedade simples. Por exemplo, se o valor de melhoramento estiver definido como $twin.tags.location e a propriedade de localização em etiquetas for um objeto que contém propriedades subordinadas como {"building": 43, "room": 503}, a mensagem é carimbada com a cadeia "$twin.tags.location".

  • Atualizações a um dispositivo duplo pode demorar até cinco minutos a refletir-se no valor de melhoramento correspondente.

  • O tamanho total da mensagem, incluindo os melhoramentos, não pode exceder os 256 KB. Se o tamanho de uma mensagem exceder os 256 KB, o hub IoT irá remover a mensagem. Pode utilizar Hub IoT métricas para identificar e depurar erros quando as mensagens são removidas. Por exemplo, pode monitorizar a métrica de mensagens telemetria incompatíveis (d2c.telemetry.egress.invalid) nas métricas de encaminhamento. Para saber mais, veja Monitorizar Hub IoT.

  • Os melhoramentos de mensagens não se aplicam a eventos de alteração de duplos digitais.

  • Os módulos não herdam etiquetas de duplos dos respetivos dispositivos correspondentes. Os melhoramentos para mensagens provenientes de módulos de dispositivos (por exemplo, de módulos IoT Edge) têm de utilizar as etiquetas de duplo que estão definidas no módulo duplo.

Preços

Os melhoramentos de mensagens estão disponíveis sem custos adicionais. Atualmente, é-lhe cobrada uma mensagem quando envia uma mensagem para um hub IoT. Só lhe é cobrada uma vez por essa mensagem, mesmo que a mensagem vá para vários pontos finais.

Passos seguintes

Consulte estes artigos para obter mais informações sobre o encaminhamento de mensagens para um hub IoT: