Conexão de dados do Hub IoT

  • Artigo

O Hub IoT do Azure é um serviço gerenciado e hospedado na nuvem que atua como hub central de mensagens para comunicação bidirecional entre o aplicativo de IoT e os dispositivos gerenciados. O Azure Data Explorer oferece ingestão contínua de Hubs IoT gerenciados pelo cliente, usando seu ponto de extremidade interno compatível com o Hub de Eventos de mensagens do dispositivo para a nuvem.

O pipeline de ingestão de IoT passa por várias etapas. Primeiro, você cria um Hub IoT e registra um dispositivo. Depois, você cria uma tabela de destino no Azure Data Explorer na qual os dados em um formato específico serão ingeridos usando as propriedades de ingestãoespecificadas. A conexão do Hub IoT precisa conhecer o roteamento de eventos para se conectar à tabela do Azure Data Explorer. Os dados são inseridos com as propriedades selecionadas de acordo com o mapeamento de propriedades do sistema de eventos. Esse processo pode ser gerenciado por meio do portal do Azure, programaticamente com o C#, o Python ou o modelo do Azure Resource Manager.

Para obter informações gerais sobre a ingestão de dados no Azure Data Explorer, confira Visão geral da ingestão de dados do Azure Data Explorer.

Formato de dados

Propriedades da ingestão

As propriedades de ingestão instruem o processo de ingestão para onde rotear os dados e como processá-los. Você pode especificar as Propriedades de ingestão dos eventos usando o EventData.Properties. Defina as seguintes propriedades:

Propriedade Descrição
Banco de dados Nome (diferenciar maiúsculas de minúsculas) do banco de dados de destino. Esta propriedade poderá ser usada se você quiser enviar os dados para um banco de dados diferente daquele no qual a conexão de dado foi criada (o padrão). Para rotear os dados para vários bancos de dados, primeiro você precisa configurar a conexão como uma conexão de vários bancos de dados. Para obter mais informações, confira Roteamento de evento.
Tabela Nome (diferenciar maiúsculas de minúsculas) da tabela de destino existente. Substitui o conjunto Table no painel Data Connection.
Formatar Formato dos dados. Substitui o conjunto Data format no painel Data Connection.
IngestionMappingReference Nome do mapeamento de ingestão existente a ser usado. Substitui o conjunto Column mapping no painel Data Connection.
Codificação Codificação de dados, o padrão é UTF8. Pode ser qualquer uma das codificações com suporte do .NET.

Observação

Somente os eventos enfileirados após a criação da conexão de dados são ingeridos.

Roteamento de eventos

Ao criar uma conexão de dados com o cluster, você especifica o roteamento para o qual enviar os dados ingeridos. O roteamento padrão é definido para a tabela de destino especificada na cadeia de conexão associada ao banco de dados de destino. O roteamento padrão dos dados também é conhecido como roteamento estático. Você pode especificar um roteamento alternativo para seus dados usando as propriedades de dados de evento.

Rotear dados de evento para um banco de dados alternativo

O roteamento de dados para um banco de dados alternativo está desativado por padrão. Para enviar os dados para um banco de dados diferente, você precisa primeiro definir a conexão como uma conexão de vários bancos de dados. Para obter um exemplo de como fazer isso no portal do Azure, consulte Ativar o roteamento de vários bancos de dados. O usuário, o grupo, a entidade de serviço ou a identidade gerenciada usada para permitir o roteamento de banco de dados precisa, pelo menos, ter a função de colaborador e permissões de gravação no cluster.

Para especificar um banco de dados alternativo, defina a propriedade de ingestãoDatabase.

Aviso

Especificar um banco de dados alternativo sem definir uma conexão de dados de vários bancos de dados causará uma falha na ingestão.

Ativar o roteamento de vários bancos de dados

Para definir um banco de dados de destino alternativo, primeiro você precisa permitir o roteamento dos dados para vários bancos de dados. Use as seguintes etapas para permitir que o roteamento dos dados alterne os bancos de dados:

  1. No portal do Azure, navegue para seu cluster.

  2. Selecione Bancos de dados>Conexões de dados.

  3. Crie ou edite uma conexão de dados e, no painel Conexão de dados, em Configurações de roteamento de dados, ative a opção Permitir roteamento de dados para outro banco de dados (conexão de dados de vários bancos de dados).

    Captura de tela do Azure Data Explorer Web U I , mostrando a opção Configurações de roteamento de dados definida para permitir.

Rotear dados de evento para uma tabela alternativa

Você também pode especificar as propriedades da tabela de destino para cada evento, usando as propriedades do evento. A conexão roteará os dados dinamicamente conforme especificado em EventData.Properties, substituindo as propriedades estáticas para esse evento. Para especificar uma tabela alternativa, defina a Propriedadede ingestão da tabela.

Observação

Se meus dados incluírem as informações de roteamento selecionadas, você deverá fornecer as informações de roteamento necessárias como parte das propriedades de eventos.

Mapeamento de propriedades do sistema de eventos

As propriedades do sistema são uma coleção usada para armazenar as propriedades definidas pelo serviço do Hub IoT, no momento em que o evento é recebido. A conexão do Hub IoT do Azure Data Explores incorporará as propriedades selecionadas na aterrissagem dos dados na tabela.

Observação

Para mapeamento de csv, as propriedades são adicionadas no início do registro na ordem listada na tabela abaixo. Para mapeamento de json, as propriedades são adicionadas de acordo com os nomes de propriedade na tabela a seguir.

Propriedades do sistema

Hub IoT expõe as seguintes propriedades do sistema para mensagens de Hub IoT dispositivo para nuvem:

Propriedade Descrição
message-id Um identificador configurável pelo usuário para a mensagem utilizada para padrões de resposta à solicitação. Formato: Uma cadeia de caracteres que diferencia maiúsculas de minúsculas (com até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
iothub-enqueuedtime Data e hora em que a mensagem Dispositivo para Nuvem foi recebida pelo Hub IoT.
user-id Uma ID usada para especificar a origem das mensagens. Quando as mensagens são geradas por Hub IoT, esse valor é definido {iot hub name}como .
iothub-connection-device-id Uma ID definida pelo Hub IoT em mensagens do dispositivo para a nuvem. Contém a deviceId do dispositivo que enviou a mensagem.
iothub-connection-module-id Uma ID definida pelo Hub IoT em mensagens do dispositivo para a nuvem. Contém a moduleId do dispositivo que enviou a mensagem.
iothub-connection-auth-generation-id Uma ID definida pelo Hub IoT em mensagens do dispositivo para a nuvem. Contém a connectionDeviceGenerationId (de acordo com as Propriedades de identidade de dispositivo) do dispositivo que enviou a mensagem.
iothub-connection-auth-method Um método de autenticação definido pelo Hub IoT em mensagens do dispositivo para a nuvem. Essa propriedade contém informações sobre o método de autenticação usado para autenticar o dispositivo que envia a mensagem.
iothub-app-iothub-creation-time-utc Permite que o dispositivo envie a hora de criação do evento ao enviar dados em um lote.
iothub-creation-time-utc Permite que o dispositivo envie a hora de criação do evento ao enviar uma mensagem em um determinado horário.
dt-dataschema Esse valor é definido pelo hub IoT em mensagens do dispositivo para a nuvem. Ele contém a ID do modelo do dispositivo definida na conexão do dispositivo.
dt-subject O nome do componente que está enviando as mensagens do dispositivo para a nuvem.

Se você selecionou Propriedades do sistema de eventos na seção Fonte de dados da tabela, inclua as propriedades no esquema e no mapeamento da tabela.

Exemplos de mapeamento de esquema

Exemplo de mapeamento de esquema

Se os dados incluírem três colunas (Timespan, Metric e Value) e as propriedades que você incluir forem iothub-connection-device-id e sequence-number, crie ou altere o esquema de tabela usando este comando:

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, IotHubDeviceId:long, IotHubSequenceNumber:long)

Exemplo de mapeamento de CSV

Execute os comandos a seguir para adicionar dados ao início do registro. Observe os valores ordinais.

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "IotHubDeviceId", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "IotHubSequenceNumber", "Properties":{"Ordinal":"1"}}'
    ']'

Exemplo de mapeamento JSON

Os dados são adicionados usando o mapeamento de propriedades do sistema. Execute estes comandos:

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.metric_value"}},'
    '    { "column" : "IotHubDeviceId", "Properties":{"Path":"$.iothub-connection-device-id"}},'
    '    { "column" : "IotHubSequenceNumber", "Properties":{"Path":"$.sequence-number"}}'
    ']'

Mapeamento das propriedades do usuário do evento

Não há suporte para enriquecer o conteúdo de eventos do Hub IoT com as propriedades do usuário. Considere inserir propriedades do usuário no corpo do evento upstream.

Cadeia Hub IoT

Observação

Para obter o melhor desempenho, crie todos os recursos na mesma região que o cluster do Azure Data Explorer.

Crie um Hub IoT

Crie um Hub IoT, caso você ainda não tenha um. A conexão com o Hub IoT pode ser gerenciada por meio do portal do Azure, programaticamente com o C#, o Python ou o modelo do Azure Resource Manager.

Observação

  • A contagem de device-to-cloud partitions não pode ser alterada, portanto você deve considerar a escala de longo prazo ao definir a contagem de partições.
  • O grupo de consumidores deve ser exclusivo por consumidor. Crie um grupo de consumidores dedicado para a conexão do Azure Data Explorer. Localize o recurso no portal do Azure e acesse Built-in endpoints para adicionar um novo grupo de consumidores.
  • A Conexão de Dados usa o Hub IoT Built-in endpoint. Se você configurar qualquer outra Message routing endpoint, as mensagens deixarão de fluir para o Built-in endpoint, a menos que uma rota seja criada para esse ponto de extremidade. Para garantir que as mensagens continuem fluindo para o ponto de extremidade integrado se uma nova rota for adicionada, configure uma rota para o ponto de extremidade de events. Para obter mais informações, confira Solucionar problemas no roteamento de mensagens do Hub IoT.

Enviando eventos

Confira o projeto de exemplo que simula um dispositivo e gera dados.

Próxima etapa

Criar uma conexão de dados Hub IoT