Enriquecimentos de mensagem para mensagens do Hub IoT do dispositivo para nuvem
Os enriquecimentos de mensagens são a capacidade do Hub IoT 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 de telemetria 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.
Um enriquecimento de mensagem tem três elementos principais:
Nome ou chave do enriquecimento
Um valor
Um ou mais pontos de extremidade para os quais o enriquecimento deve ser aplicado.
A chave é uma cadeia de caracteres. Uma chave pode conter apenas caracteres alfanuméricos ou estes caracteres especiais: hífen (-), sublinhado (_) e ponto final (.).
O valor pode ser qualquer um dos seguintes exemplos:
Qualquer cadeia de caracteres estática. Valores dinâmicos, como condições, lógica, operações e funções, não são permitidos. Por exemplo, se você desenvolver um aplicativo SaaS que é usado por vários clientes, poderá atribuir um identificador a cada cliente e disponibilizá-lo no aplicativo. Quando o aplicativo for executado, o Hub IoT aplicará um carimbo de data/hora às mensagens de telemetria do dispositivo com o identificador do cliente, tornando possível processar as mensagens de maneira diferente para cada cliente.
O nome do Hub IoT que envia a mensagem. Esse valor é $iothubname.
Informações do dispositivo gêmeo, como seu caminho. Alguns exemplos são $twin.tags.field e $twin.tags.latitude.
Observação
Neste momento, somente $iothubname, $twin.tags, $twin.properties.desired e $twin.properties.reported são variáveis com suporte ao enriquecimento de mensagens. Além disso, somente os tipos primitivos têm suporte para enriquecimento. As mensagens não podem ser enriquecidas com tipos de objeto.
Os enriquecimentos de mensagens são adicionados como propriedades do aplicativo às mensagens enviadas para os pontos de extremidade escolhidos.
Aplicando enriquecimentos
As mensagens podem vir de qualquer fonte de dados com suporte pelo Roteamento de mensagens do Hub IoT, incluindo os seguintes exemplos:
- telemetria do dispositivo, como temperatura ou pressão
- notificações de alteração do dispositivo gêmeo – alterações no dispositivo gêmeo
- eventos do ciclo de vida do dispositivo, como quando o dispositivo é criado ou excluído
Você pode adicionar enriquecimentos a mensagens que vão para o ponto de extremidade interno de um hub IoT ou mensagens que estão sendo roteadas para pontos de extremidade personalizados como o Armazenamento de Blobs do Azure, uma fila do Barramento de Serviço ou um tópico do Barramento de Serviço.
Você também pode adicionar aprimoramentos a mensagens que sejam publicadas na Grade de Eventos, primeiro criando uma assinatura de grade de eventos com o tipo de mensagem de telemetria do dispositivo. Com base nessa assinatura, criaremos uma rota padrão no Hub IoT do Azure para a telemetria. Essa rota única pode lidar com todas as suas assinaturas de Grade de Eventos. Em seguida, você pode configurar enriquecimentos para o ponto de extremidade usando a guia Enriquecer mensagens da seção Roteamento de mensagens do Hub IoT. Para obter informações sobre como reagir a eventos usando a Grade de Eventos, confira Hub IoT e Grade de Eventos.
Os enriquecimentos são aplicados por ponto de extremidade. Se você especificar cinco enriquecimentos a serem carimbados para um ponto de extremidade específico, todas as mensagens que vão para esse ponto de extremidade serão carimbadas com os mesmos cinco enriquecimentos.
Os enriquecimentos podem ser configurados usando os seguintes métodos:
| Método | Comando |
|---|---|
| Portal | Portal do Azure Confira o tutorial de enriquecimentos de mensagens |
| CLI do Azure | az iot hub message-enrichment |
| Azure PowerShell | Add-AzIotHubMessageEnrichment |
A adição de enriquecimentos de mensagem não adiciona latência ao roteamento de mensagens.
Para experimentar os enriquecimentos de mensagens, confira o tutorial de enriquecimentos de mensagens
Limitações
Você pode adicionar até 10 enriquecimentos por hub IoT para esses hubs na camada standard ou básica. Para os hubs IoT na camada gratuita, você pode adicionar até 2 enriquecimentos.
Em alguns casos, se você estiver enriquecendo uma mensagem com um valor definido para uma marca ou propriedade no dispositivo gêmeo, o valor será carimbado com o caminho do dispositivo gêmeo especificado. Por exemplo, se um valor de enriquecimento for definido como $twin.tags.field, as mensagens serão carimbadas com a cadeia de caracteres "$twin.tags.field" em vez de o valor desse campo do texto. Isso acontece nos seguintes casos:
O hub IoT está na camada básica. Os Hubs IoT da camada básica não dão suporte a dispositivos gêmeos.
O Hub IoT está na camada standard, mas o caminho do dispositivo gêmeo usado para o valor do enriquecimento não existe. Por exemplo, se o valor de enriquecimento for definido como $twin.tags.location e o dispositivo gêmeo não tiver uma propriedade de localização nas tags, a mensagem será carimbada com a cadeia de caracteres "$twin.tags.location".
O hub IoT está na camada Standard, mas o caminho de Altova do dispositivo usado para o valor do enriquecimento é resolvido para um objeto, em vez de uma propriedade simples. Por exemplo, se o valor de enriquecimento for definido como $twin.tags.location e a propriedade de localização nas tags for um objeto que contém propriedades filho como
{"building": 43, "room": 503}, a mensagem será carimbada com a cadeia de caracteres "$twin.tags.location".
As atualizações em um dispositivo gêmeo podem levar até cinco minutos para serem refletidos no valor de enriquecimento correspondente.
O tamanho total da mensagem, incluindo os enriquecimentos, não pode exceder 256 KB. Se um tamanho de mensagem exceder 256 KB, o hub IoT removerá a mensagem. Você pode usar métricas do Hub IoT para identificar e depurar erros quando as mensagens são descartadas. Por exemplo, você pode monitorar a métrica mensagens de telemetria incompatíveis (d2c.telemetry.egress.invalid) nas métricas de roteamento. Para saber mais, confira Monitorar o Hub IoT.
Os enriquecimentos de mensagens não se aplicam a eventos de alteração do gêmeo digital.
Os módulos não herdam marcações gêmeos de seus dispositivos correspondentes. Os enriquecimentos para mensagens originadas de módulos de dispositivo (por exemplo, de módulos IoT Edge) devem usar as marcações gêmeos definidas no módulo gêmeo.
Preços
Os enriquecimentos de mensagens estão disponíveis sem custo adicional. No momento, você é cobrado quando envia uma mensagem para um Hub IoT. Você é cobrado apenas uma vez por essa mensagem, mesmo que ela vá para vários pontos de extremidade.
Próximas etapas
Confira estes artigos para obter mais informações sobre como rotear mensagens para um hub IoT: