Enriquecimento de mensagens para mensagens de dispositivo para nuvem no Hub IoT

Enriquecimento de mensagens é a capacidade de um hub IoT 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 telemetria de dispositivo com uma etiqueta do gêmeo digital do dispositivo pode reduzir a carga sobre os clientes para fazer chamadas à API do gêmeo digital do dispositivo para obter essas informações.

O enriquecimento da mensagem tem três elementos-chave:

• Nome ou chave de enriquecimento

• Um valor

• Um ou mais parâmetros aos quais o enriquecimento deve ser aplicado.

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

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 usado por vários clientes, poderá atribuir um identificador a cada cliente e disponibilizar esse identificador no aplicativo. Quando o aplicativo é executado, o Hub IoT carimba 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 que envia a mensagem. Este valor é $iothubname.

• Informações do dispositivo gêmeo, como seu caminho. Exemplos seriam $twin.tags.field e $twin.tags.latitude.

  Observação

  No momento, apenas $iothubname, $twin.tags, $twin.properties.desired e $twin.properties.reported são variáveis suportadas para enriquecimento de mensagens. Além disso, apenas tipos primitivos são suportados para enriquecimentos. As mensagens não podem ser enriquecidas com tipos de objeto.

Os Enriquecimentos de Mensagens são adicionados como propriedades de aplicativo às mensagens enviadas ao(s) ponto(s) de extremidade escolhido(s).

Aplicar enriquecimentos

As mensagens podem vir de qualquer fonte de dados suportada pelo roteamento de mensagens do Hub IoT, incluindo os seguintes exemplos:

• telemetria do dispositivo, como temperatura ou pressão
• notificações de alteração de gêmeo de dispositivo -- alterações no gêmeo de dispositivo
• eventos do ciclo de vida do dispositivo, como quando o dispositivo é criado ou excluído

Você pode adicionar enriquecimentos a mensagens que estão indo para o endpoint incorporado de um Hub IoT ou a mensagens que estão sendo roteadas para endpoints personalizados, como o Azure Blob Storage, uma fila do Service Bus ou um tópico do Service Bus.

Você também pode adicionar enriquecimentos às mensagens que estão sendo publicadas na Grade de Eventos criando primeiro uma assinatura da 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. Uma única rota pode gerir todas as suas subscrições do Event Grid. Em seguida, pode configurar os enriquecimentos para o endpoint na 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, consulte 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.

O enriquecimento pode ser configurado usando os seguintes métodos:

Adicionar enriquecimento de mensagem não adiciona latência ao roteamento de mensagens.

Para experimentar o enriquecimento de mensagens, consulte o tutorial de enriquecimento de mensagens

Limitações

• Você pode adicionar até 10 enriquecimentos por hub IoT para esses hubs na camada padrão ou básica. Para hubs IoT no nível gratuito, você pode adicionar até 2 enriquecimentos.

• Em alguns casos, se estiveres a enriquecer uma mensagem com um valor atribuído como uma tag ou propriedade no gémeo digital do dispositivo, o valor será carimbado com o caminho especificado do gémeo digital do dispositivo. Por exemplo, se um valor de enriquecimento for definido como $twin.tags.field, as mensagens serão marcadas com a string "$twin.tags.field", em vez do valor desse campo no twin. Esse comportamento acontece nos seguintes casos:

  • Seu hub IoT está na camada básica. Os hubs IoT de camada básica não suportam gêmeos de dispositivo.

  • Seu hub IoT está na camada padrão, mas o caminho gêmeo do dispositivo usado para o valor do enriquecimento não existe. Por exemplo, se o valor de enriquecimento estiver definido como $twin.tags.___location e o dispositivo gêmeo não tiver uma propriedade de localização em tags, a mensagem será marcada com a string "$twin.tags.___location".

  • Seu hub IoT está na camada padrão, mas o caminho gêmeo 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 estiver definido como $twin.tags.___location e a propriedade ___location em tags é um objeto que contém propriedades-filhas como {"building": 43, "room": 503}, a mensagem será carimbada com a sequência de caracteres "$twin.tags.___location".

• As atualizações de um dispositivo twin podem levar até cinco minutos para serem refletidas no valor de enriquecimento correspondente.

• O tamanho total da mensagem, incluindo os enriquecimentos, não pode exceder 256 KB. Se o tamanho de uma mensagem exceder 256 KB, o hub IoT descartará 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 de mensagens de telemetria incompatíveis (d2c.telemetry.egress.invalid) nas métricas de roteamento. Para saber mais, consulte Monitorar o Hub IoT.

• Os enriquecimentos de mensagens não se aplicam a eventos de alteração de gêmeos digitais.

• Os módulos não herdam tags gêmeas de seus dispositivos correspondentes. O enriquecimento para mensagens originadas de módulos de dispositivo (por exemplo, de módulos IoT Edge) deve usar as tags gêmeas definidas no módulo gêmeo.

Preços

O enriquecimento de mensagens está disponível sem custo adicional. Atualmente, você é cobrado quando envia uma mensagem para um hub IoT. Você só será cobrado uma vez por essa mensagem, mesmo que seja enviada para vários destinos.

Próximos passos

Confira estes artigos para obter mais informações sobre como rotear mensagens para um hub IoT:

• Tutorial de enriquecimento de mensagens

• Usar o roteamento de mensagens do Hub IoT para enviar mensagens do dispositivo para a nuvem para diferentes pontos de extremidade

• Tutorial: Roteamento do Hub IoT