Ligação de dados do Hub IoT

  • Artigo

Hub IoT do Azure é um serviço gerido, alojado na cloud, que atua como um hub de mensagens central para comunicação bidirecional entre a sua aplicação IoT e os dispositivos que gere. O Azure Data Explorer oferece ingestão contínua de Hubs IoT geridos pelo cliente, utilizando o respetivo Hub de Eventos compatível com o ponto final incorporado de mensagens do dispositivo para a cloud.

O pipeline de ingestão de IoT percorre vários passos. Primeiro, crie um Hub IoT e registe um dispositivo no mesmo. Em seguida, irá criar uma tabela de destino no Azure Data Explorer em que os dados num formato específico serão ingeridos com as propriedades de ingestão especificadas. A ligação do Hub Iot precisa de saber o encaminhamento de eventos para ligar à tabela Data Explorer do Azure. Os dados são incorporados com propriedades selecionadas de acordo com o mapeamento de propriedades do sistema de eventos. Este processo pode ser gerido através do portal do Azure, programaticamente com C# ou Python, ou com o modelo Resource Manager do Azure.

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

Formato de dados

Propriedades de ingestão

As propriedades de ingestão instruem o processo de ingestão para onde encaminhar os dados e como processá-lo. Pode especificar as propriedades de Ingestão dos eventos com EventData.Properties. Pode definir as seguintes propriedades:

Propriedade Descrição
Base de Dados Nome (sensível a maiúsculas e minúsculas) da base de dados de destino. Esta propriedade pode ser utilizada se quiser enviar os dados para uma base de dados diferente da base de dados em que a ligação de dados foi criada (a base de dados predefinida). Para encaminhar os dados para várias bases de dados, primeiro tem de configurar a ligação como uma ligação de várias bases de dados. Para obter mais informações, veja Encaminhamento de eventos.
Tabela Nome (sensível a maiúsculas e minúsculas) da tabela de destino existente. Substitui o Table conjunto no Data Connection painel.
Formato Formato de dados. Substitui o Data format conjunto no Data Connection painel.
IngestionMappingReference Nome do mapeamento de ingestão existente a utilizar. Substitui o Column mapping conjunto no Data Connection painel.
Encoding Codificação de dados, a predefinição é UTF8. Pode ser qualquer uma das codificações suportadas pelo .NET.

Nota

Apenas os eventos colocados em fila após criar a ligação de dados são ingeridos.

Encaminhamento de eventos

Quando cria uma ligação de dados ao cluster, especifica o encaminhamento para onde enviar dados ingeridos. O encaminhamento predefinido é para a tabela de destino especificada na cadeia de ligação que está associada à base de dados de destino. O encaminhamento predefinido para os seus dados também é referido como encaminhamento estático. Pode especificar um encaminhamento alternativo para os seus dados com as propriedades de dados do evento.

Encaminhar dados de eventos para uma base de dados alternativa

Por predefinição, o encaminhamento de dados para uma base de dados alternativa está desativado. Para enviar os dados para uma base de dados diferente, primeiro tem de definir a ligação como uma ligação de várias bases de dados. Para obter um exemplo de como fazê-lo no portal do Azure, veja Ativar o encaminhamento de várias bases de dados. O utilizador, grupo, principal de serviço ou identidade gerida utilizada para permitir o encaminhamento de bases de dados tem, pelo menos, de ter a função de contribuidor e as permissões de escrita no cluster.

Para especificar uma base de dados alternativa, defina a propriedade Ingestão debases de dados.

Aviso

Especificar uma base de dados alternativa sem definir a ligação como uma ligação de dados de várias bases de dados fará com que a ingestão falhe.

Ativar o encaminhamento de várias bases de dados

Antes de poder definir uma base de dados de destino alternativa, primeiro tem de permitir o encaminhamento dos dados para várias bases de dados. Utilize os seguintes passos para permitir o encaminhamento dos dados para bases de dados alternativas:

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

  2. Selecione Bases de>Dados Ligações de dados.

  3. Crie ou edite uma ligação de dados e, no painel Ligação de dados , em Definições de encaminhamento de dados, ative a opção permitir encaminhamento de dados para outra base de dados (ligação de dados de várias bases de dados).

    Captura de ecrã do Azure Data Explorer Web U I , com a opção Definições de encaminhamento de dados definida para permitir.

Encaminhar dados de eventos para uma tabela alternativa

Também pode especificar as propriedades da tabela de destino para cada evento com as propriedades do evento. A ligação encaminhará dinamicamente os dados conforme especificado em EventData.Properties, substituindo as propriedades estáticas deste evento. Para especificar uma tabela alternativa, defina a propriedade Ingestão de tabelas.

Nota

Se os meus dados incluirem informações de encaminhamento selecionadas, tem de fornecer as informações de encaminhamento necessárias como parte das propriedades dos eventos.

Mapeamento de propriedades do sistema de eventos

As propriedades do sistema são uma coleção utilizada para armazenar propriedades definidas pelo serviço Hub IoT, no momento em que o evento é recebido. A ligação Data Explorer Hub IoT do Azure incorporará as propriedades selecionadas na destino de dados na tabela.

Nota

Para csv mapeamento, as propriedades são adicionadas no início do registo pela ordem listada na tabela abaixo. Para json mapeamento, as propriedades são adicionadas de acordo com os nomes de propriedades na tabela seguinte.

Propriedades do sistema

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

Propriedade Descrição
id de mensagem Um identificador de definição de utilizador para a mensagem utilizada para padrões de pedido-resposta. Formatar: uma cadeia sensível a maiúsculas e minúsculas (até 128 carateres) de carateres alfanuméricos ascii de 7 bits + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
iothub-enqueuedtime Data e hora em que a mensagem Dispositivo para a Nuvem foi recebida por Hub IoT.
user-id Um ID utilizado para especificar a origem das mensagens. Quando as mensagens são geradas por Hub IoT, este valor é definido como {iot hub name}.
iothub-connection-device-id Um ID definido por Hub IoT em mensagens do dispositivo para a cloud. Contém o deviceId do dispositivo que enviou a mensagem.
iothub-connection-module-id Um ID definido por Hub IoT em mensagens do dispositivo para a cloud. Contém o moduleId do dispositivo que enviou a mensagem.
iothub-connection-auth-generation-id Um ID definido por Hub IoT em mensagens do dispositivo para a cloud. Contém a connectionDeviceGenerationId (de acordo com as propriedades de identidade do dispositivo) do dispositivo que enviou a mensagem.
iothub-connection-auth-method Um método de autenticação definido por Hub IoT em mensagens do dispositivo para a cloud. Esta propriedade contém informações sobre o método de autenticação utilizado para autenticar o dispositivo que envia a mensagem.
iothub-app-iothub-creation-time-utc Permite que o dispositivo envie a hora de criação de eventos ao enviar dados num lote.
iothub-creation-time-utc Permite que o dispositivo envie a hora de criação de eventos ao enviar uma mensagem de cada vez.
dt-dataschema Este valor é definido pelo hub IoT em mensagens do dispositivo para a cloud. Contém o ID do modelo de dispositivo definido na ligação do dispositivo.
dt-subject O nome do componente que está a enviar as mensagens do dispositivo para a cloud.

Se tiver selecionado as propriedades do sistema de eventos na secção Origem de Dados da tabela, tem de incluir as propriedades no esquema e mapeamento da tabela.

Exemplos de mapeamento de esquemas

Exemplo de mapeamento de esquema de tabela

Se os seus dados incluírem três colunas (Timespan, Metrice Value) e as propriedades que incluir são iothub-connection-device-id e sequence-number, crie ou altere o esquema da tabela com este comando:

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

Exemplo de mapeamento CSV

Execute os seguintes comandos para adicionar dados ao início do registo. Anote 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 através do 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 de propriedades do utilizador do evento

Não existe suporte para melhorar o payload de eventos Hub IoT com as propriedades do utilizador. Considere incorporar propriedades de utilizador no corpo do evento a montante.

ligação Hub IoT

Nota

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

Criar um Hub IoT

Se ainda não tiver um, crie um Hub Iot. A ligação ao Hub IoT pode ser gerida através do portal do Azure, programaticamente com C# ou Python, ou com o modelo Resource Manager do Azure.

Nota

  • A device-to-cloud partitions contagem não é alterável, pelo que deve considerar a escala de longo prazo ao definir a contagem de partições.
  • O grupo de consumidores tem de ser exclusivo por consumidor. Crie um grupo de consumidores dedicado à ligação Data Explorer do Azure. Localize o recurso no portal do Azure e aceda a Built-in endpoints adicionar um novo grupo de consumidores.
  • A Ligação de Dados utiliza Hub IoT Built-in endpoint. Se configurar outras Message routing endpointmensagens , as mensagens deixam de fluir para o, a Built-in endpoint menos que seja criada uma rota para esse ponto final. Para garantir que as mensagens continuam a fluir para o ponto final incorporado se for adicionada uma nova rota, configure uma rota para o events ponto final. Para obter mais informações, veja Hub IoT Resolução de Problemas de Encaminhamento de Mensagens.

Enviar eventos

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

Passo seguinte

Criar uma ligação de dados Hub IoT