Transforme dados dentro do seu aplicativo IoT Central para exportação

Os dispositivos IoT enviam dados em vários formatos. Para usar os dados do dispositivo em sua solução IoT, talvez seja necessário transformar os dados do dispositivo antes de exportá-los para outros serviços.

Este artigo mostra como transformar dados de dispositivo como parte de uma definição de exportação de dados em um aplicativo do IoT Central.

As transformações em uma definição de exportação de dados do IoT Central permitem manipular o formato e a estrutura dos dados do dispositivo antes de exportá-los para um destino. Você pode especificar uma transformação para cada destino em uma definição de exportação. Cada mensagem passa pela transformação para criar um registro de saída para exportar para o destino.

Use transformações para reestruturar cargas úteis JSON, renomear campos, filtrar campos e executar cálculos simples em valores de telemetria. Por exemplo, use uma transformação para converter suas mensagens em um formato tabular que corresponda ao esquema de um destino, como uma tabela do Azure Data Explorer.

O vídeo a seguir apresenta as transformações de dados do IoT Central:

Adicionar uma transformação

Para adicionar uma transformação para um destino em sua definição de exportação de dados, selecione + Transformar , conforme mostrado na captura de tela a seguir:

O painel Transformação de dados permite especificar a transformação. No 1. Adicione sua seção de mensagem de entrada, você pode inserir uma mensagem de exemplo que deseja passar pela transformação. Você também pode gerar uma mensagem de exemplo selecionando um modelo de dispositivo. No 2. Seção de consulta de transformação de compilação, você pode inserir a consulta que transforma a mensagem de entrada. O 3. A seção Visualizar mensagens de saída mostra o resultado da transformação:

Criar uma consulta de transformação

O mecanismo de transformação usa o processador JSON JQ de código aberto para reestruturar e formatar cargas úteis JSON. Para especificar uma transformação, escreva uma consulta JQ, que pode usar os filtros, funções e recursos internos do JQ. Para obter alguns exemplos de consulta, consulte Exemplos de consultas de transformação. Para saber mais sobre como escrever consultas JQ, consulte o manual JQ.

Estrutura da mensagem de pré-transformação

Você pode exportar os seguintes fluxos de dados do IoT Central: telemetria, alterações de propriedade, eventos de conectividade de dispositivo, eventos de ciclo de vida do dispositivo e eventos de ciclo de vida do modelo de dispositivo. Cada tipo de dados tem uma estrutura específica que inclui informações como valores de telemetria, informações do aplicativo, metadados do dispositivo e valores de propriedade.

O exemplo a seguir mostra a forma da mensagem de telemetria. Todos esses dados estão disponíveis para a sua transformação. A estrutura da mensagem é semelhante para outros tipos de mensagem, mas existem alguns campos específicos do tipo. Você pode usar o recurso Adicionar sua mensagem de entrada para gerar uma mensagem de exemplo com base em um modelo de dispositivo em seu aplicativo.

{
  "applicationId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "device": {
    "id": "31edabe6-e0b9-4c83-b0df-d12e95745b9f",
    "name": "Scripted Device - 31edabe6-e0b9-4c83-b0df-d12e95745b9f",
    "cloudProperties": [],
    "properties": {
      "reported": [
        {
          "id": "urn:smartKneeBrace:Smart_Vitals_Patch_wr:FirmwareVersion:1",
          "name": "FirmwareVersion",
          "value": 1.0
        }
      ]
    },
    "templateId": "urn:sbq3croo:modelDefinition:nf7st1wn3",
    "templateName": "Smart Knee Brace"
  },
  "telemetry": [
      {
        "id": "urn:continuousPatientMonitoringTemplate:Smart_Knee_Brace_6wm:Acceleration:1",
        "name": "Acceleration",
        "value": {
          "x": 19.212770659918583,
          "y": 20.596296675217335,
          "z": 54.04859440697045
        }
      },
      {
        "id": "urn:continuousPatientMonitoringTemplate:Smart_Knee_Brace_6wm:RangeOfMotion:1",
        "name": "RangeOfMotion",
        "value": 110
      }
  ],
  "enqueuedTime": "2021-03-23T19:55:56.971Z",
  "enrichments": {
      "your-enrichment-key": "enrichment-value"
  },
  "messageProperties": {
      "prop1": "prop-value"
  },
  "messageSource": "telemetry"
}

Exemplo de consultas de transformação

Os exemplos de consulta a seguir usam a mensagem de telemetria mostrada na seção anterior.

Exemplo 1: A seguinte consulta JQ gera a saída de cada parte da telemetria da mensagem de entrada como uma mensagem de saída separada:

.telemetry[]

Saída JSON:

{
  "id": "urn:continuousPatientMonitoringTemplate:Smart_Knee_Brace_6wm:Acceleration:1",
  "name": "Acceleration",
  "value": {
    "x": 19.212770659918583,
    "y": 20.596296675217335,
    "z": 54.04859440697045
  }
},
{
  "id": "urn:continuousPatientMonitoringTemplate:Smart_Knee_Brace_6wm:RangeOfMotion:1",
  "name": "RangeOfMotion",
  "value": 110
}

Exemplo 2: A seguinte consulta JQ converte a matriz de telemetria de entrada em um objeto com nomes de telemetria como chaves:

.telemetry | map({ key: .name, value: .value }) | from_entries

Saída JSON:

{
  "Acceleration": {
    "x": 19.212770659918583,
    "y": 20.596296675217335,
    "z": 54.04859440697045
  },
  "RangeOfMotion": 110
}

Exemplo 3: A consulta JQ a seguir localiza o valor de telemetria RangeOfMotion e o converte de graus em radianos usando a fórmula rad = degree * pi / 180. Esta consulta também mostra como importar e usar o iotc módulo:

import "iotc" as iotc;
{
  rangeOfMotion: (
    .telemetry
    | iotc::find(.name == "RangeOfMotion").value
    | . * 3.14159265358979323846 / 180
  )
}

Saída JSON:

{
  "rangeOfMotion": 1.9198621771937625
}

Exemplo 4: Para manipular a mensagem de entrada em um formato tabular, você pode mapear cada mensagem exportada em uma ou mais linhas. A saída de linha é logicamente representada como um objeto JSON onde o nome da coluna é a chave e o valor da coluna é o valor:

{
    "<column 1 name>": "<column 1 value>",
    "<column 2 name>": "<column 2 value>",
    ...
}

A consulta JQ a seguir grava linhas em uma tabela que armazena a telemetria rangeOfMotion em diferentes dispositivos. A consulta mapeia o ID do dispositivo, o tempo enfileirado e a amplitude de movimento em uma tabela com estas colunas:

import "iotc" as iotc;
{
    deviceId: .deviceId,
    timestamp: .enqueuedTime,
    rangeOfMotion: .telemetry | iotc::find(.name == "RangeOfMotion").value
}

Saída em formato JSON:

{
  "deviceId": "31edabe6-e0b9-4c83-b0df-d12e95745b9f",
  "timestamp": "2021-03-23T19:55:56.971Z",
  "rangeOfMotion": 110
}

Módulo IoT Central

Um módulo JQ é uma coleção de funções personalizadas. Como parte de sua consulta de transformação, você pode importar um módulo específico interno do IoT Central que contém funções para facilitar a escrita de suas consultas. Para importar o módulo IoT Central, use a seguinte diretiva:

import "iotc" as iotc;

O módulo IoT Central inclui as seguintes funções:

find(expression): A find função permite que você encontre um elemento de matriz específico, como valor de telemetria ou entrada de propriedade em sua carga útil. A entrada da função é uma matriz e o parâmetro define um filtro JQ para ser executado em cada elemento da matriz. A função retorna cada elemento de matriz onde o filtro é avaliado como true:

Por exemplo, para localizar um valor de telemetria específico chamado RangeOfMotion:

.telemetry | iotc::find(.name == "RangeOfMotion")

Cenários

Os cenários a seguir usam a funcionalidade de transformação para personalizar o formato de dados do dispositivo para um destino específico.

Cenário 1: Exportar dados do dispositivo para o Azure Data Explorer

Nesse cenário, você transforma os dados do dispositivo para corresponder ao esquema fixo no Azure Data Explorer, onde cada valor de telemetria aparece como uma coluna na tabela e cada linha representa uma única mensagem. Por exemplo:

Para exportar dados compatíveis com esta tabela, cada mensagem exportada deve ser semelhante ao objeto a seguir. O objeto representa uma única linha, onde as chaves são nomes de colunas e os valores são o valor a ser colocado em cada coluna:

{
    "Timestamp": <value-of-Timestamp>,
    "DeviceId": <value-of-deviceId>,
    "T1": <value-of-T1>,
    "T2": <value-of-T2>,
    "T3": <value-of-T3>,
}

Nesse cenário, o dispositivo envia os valores , t2e t3 telemetria t1em uma mensagem de entrada que se parece com o exemplo a seguir:

{
  "applicationId": "11112222-bbbb-3333-cccc-4444dddd5555",
  "enqueuedTime": "1933-01-26T03:10:44.480001324Z",
  "messageSource": "telemetry",
  "telemetry": [
    {
      "id": "dtmi:temperaturesensor288:sensors1lr:t1;1",
      "name": "t1",
      "value": 1.1889838348731093e+308
    },
    {
      "id": "dtmi:temperaturesensor288:sensors1lr:t2;1",
      "name": "t2",
      "value": 1.4347093391531383e+308
    },
    {
      "id": "dtmi:temperaturesensor288:sensors1lr:t3;1",
      "name": "t3",
      "value": 2.9700885230380616e+307
    }
  ],
  "device": {
    "id": "oozrnl1zs857",
    "name": "haptic alarm",
    "templateId": "dtmi:modelDefinition:nhhbjotee:qytxnp8hi",
    "templateName": "hapticsensors",
    "properties": {
      "reported": []
    },
    "cloudProperties": [],
    "simulated": true,
    "approved": false,
    "blocked": false,
    "provisioned": true
  }
}

A consulta JQ a seguir gera os T1valores , T2 e T3 telemetria, o Timestamp e como deviceId uma mensagem com pares chave-valor correspondentes ao esquema de tabela do Azure Data Explorer:

import "iotc" as iotc;
{
  deviceId: .device.id,
  Timestamp: .enqueuedTime,
  T1: .telemetry | iotc::find(.name == "t1").value,
  T2: .telemetry | iotc::find(.name == "t2").value,
  T3: .telemetry | iotc::find(.name == "t3").value,
}

Saída JSON:

{
  "T1": 1.1889838348731093e+308,
  "T2": 1.4347093391531383e+308,
  "T3": 2.9700885230380616e+307,
  "Timestamp": "1933-01-26T03:10:44.480001324Z",
  "deviceId": "oozrnl1zs857"
}

Para saber mais sobre como adicionar um cluster e um banco de dados do Azure Data Explorer como um destino de exportação, consulte Criar um destino do Azure Data Explorer.

Cenário 2: Desmembrando uma matriz de telemetria

Nesse cenário, o dispositivo envia a seguinte matriz de telemetria em uma mensagem:

{
  "applicationId": "22223333-cccc-4444-dddd-5555eeee6666",
  "enqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "messageSource": "telemetry",
  "telemetry": [
    {
      "id": "dtmi:sample1:data;1",
      "name": "data",
      "value": [
        {
          "id": "subdevice1",
          "values": {
              "running": true,
              "cycleCount": 2315
          }
        },
        {
          "id": "subdevice2",
          "values": {
              "running": false,
              "cycleCount": 824567
          }
        }
      ]
    },
    {
      "id": "dtmi:sample1:parentStatus;1",
      "name": "parentStatus",
      "value": "healthy"
    }
  ],
  "device": {
    "id": "9xwhr7khkfri",
    "name": "wireless port",
    "templateId": "dtmi:hpzy1kfcbt2:umua7dplmbd",
    "templateName": "Smart Vitals Patch",
    "properties": {
      "reported": [
        {
          "id": "dtmi:sample1:prop;1",
          "name": "Connectivity",
          "value": "Tenetur ut quasi minus ratione voluptatem."
        }
      ]
    },
    "cloudProperties": [],
    "simulated": true,
    "approved": true,
    "blocked": false,
    "provisioned": false
  }
}

Você deseja transformar esses dados de dispositivo para corresponder ao seguinte esquema de tabela:

A consulta JQ a seguir cria uma mensagem de saída separada para cada entrada de subdispositivo na mensagem e inclui algumas informações comuns da mensagem base e do dispositivo pai. Essa consulta nivela a saída e separa as divisões lógicas em seus dados que chegaram como uma única mensagem:

import "iotc" as iotc;
{
    enqueuedTime: .enqueuedTime,
    deviceId: .device.id,
    parentStatus: .telemetry | iotc::find(.name == "parentStatus").value
} + (
    .telemetry
    | iotc::find(.name == "data").value[]
    | {
        subdeviceId: .id,
        running: .values.running,
        cycleCount: .values.cycleCount
    }
)

Saída JSON:

{
    "cycleCount": 2315,
    "deviceId": "9xwhr7khkfri",
    "enqueuedTime": "1909-10-10T07:11:56.078161042Z",
    "parentStatus": "healthy",
    "running": true,
    "subdeviceId": "subdevice1"
},
{
    "cycleCount": 824567,
    "deviceId": "9xwhr7khkfri",
    "enqueuedTime": "1909-10-10T07:11:56.078161042Z",
    "parentStatus": "healthy",
    "running": false,
    "subdeviceId": "subdevice2"
}

Cenário 3: Streaming do Power BI

O recurso de streaming em tempo real do Power BI permite exibir dados em um painel que é atualizado em tempo real com baixa latência. Para saber mais, consulte Streaming em tempo real no Power BI.

Para usar o IoT Central com o Power BI Streaming, configure uma exportação de webhook que envie corpos de solicitação em um formato específico. Este exemplo pressupõe que você tenha um conjunto de dados do Power BI Streaming com o seguinte esquema:

  {
    "bloodPressureDiastolic": 161438124,
    "bloodPressureSystolic": -966387879,
    "deviceId": "9xwhr7khkfri",
    "deviceName": "wireless port",
    "heartRate": -633994413,
    "heartRateVariability": -37514094,
    "respiratoryRate": 1582211310,
    "timestamp": "1909-10-10T07:11:56.078161042Z"
  }

Para criar o destino de exportação do webhook, você precisa do ponto de extremidade REST API URL para seu conjunto de dados de streaming do Power BI.

Nesse cenário, o dispositivo envia mensagens de telemetria que se parecem com o exemplo a seguir:

{
  "applicationId": "22223333-cccc-4444-dddd-5555eeee6666",
  "enqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "messageSource": "telemetry",
  "telemetry": [
    {
      "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:HeartRate;1",
      "name": "HeartRate",
      "value": -633994413
    },
    {
      "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:RespiratoryRate;1",
      "name": "RespiratoryRate",
      "value": 1582211310
    },
    {
      "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:HeartRateVariability;1",
      "name": "HeartRateVariability",
      "value": -37514094
    },
    {
      "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:BodyTemperature;1",
      "name": "BodyTemperature",
      "value": 5.323322666478241e+307
    },
    {
      "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:FallDetection;1",
      "name": "FallDetection",
      "value": "Earum est nobis at voluptas id qui."
    },
    {
      "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:BloodPressure;1",
      "name": "BloodPressure",
      "value": {
        "Diastolic": 161438124,
        "Systolic": -966387879
      }
    }
  ],
  "device": {
    "id": "9xwhr7khkfri",
    "name": "wireless port",
    "templateId": "dtmi:hpzy1kfcbt2:umua7dplmbd",
    "templateName": "Smart Vitals Patch",
    "properties": {
      "reported": [
        {
          "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_wr:DeviceStatus;1",
          "name": "DeviceStatus",
          "value": "Id optio iste vero et neque sit."
        }
      ]
    },
    "cloudProperties": [],
    "simulated": true,
    "approved": true,
    "blocked": false,
    "provisioned": false
  }
}

A consulta JQ a seguir transforma a mensagem de entrada em um formato adequado para o webhook enviar para o conjunto de dados de streaming do Power BI. Este exemplo inclui uma condição de filtro para apenas mensagens de saída para um modelo de dispositivo específico. Você pode usar o recurso de filtro de exportação de dados para filtrar por modelo de dispositivo:

import "iotc" as iotc;
if .device.templateId == "dtmi:hpzy1kfcbt2:umua7dplmbd" then 
    {
        deviceId: .device.id,
        timestamp: .enqueuedTime,
        deviceName: .device.name,
        bloodPressureSystolic: .telemetry | iotc::find(.name == "BloodPressure").value.Systolic,
        bloodPressureDiastolic: .telemetry | iotc::find(.name == "BloodPressure").value.Diastolic,
        heartRate: .telemetry | iotc::find(.name == "HeartRate").value,
        heartRateVariability: .telemetry | iotc::find(.name == "HeartRateVariability").value,
        respiratoryRate: .telemetry | iotc::find(.name == "RespiratoryRate").value
    }
else
    empty
end

Saída JSON:

{
  "bloodPressureDiastolic": 161438124,
  "bloodPressureSystolic": -966387879,
  "deviceId": "9xwhr7khkfri",
  "deviceName": "wireless port",
  "heartRate": -633994413,
  "heartRateVariability": -37514094,
  "respiratoryRate": 1582211310,
  "timestamp": "1909-10-10T07:11:56.078161042Z"
}

Cenário 4: Exportar dados para o Azure Data Explorer e visualizá-los no Power BI

Nesse cenário, você exporta dados para o Azure Data Explorer e, em seguida, usa um conector para visualizar os dados no Power BI. Para saber mais sobre como adicionar um cluster e um banco de dados do Azure Data Explorer como um destino de exportação, consulte Criar um destino do Azure Data Explorer.

Este cenário usa uma tabela do Azure Data Explorer com o seguinte esquema:

.create table smartvitalspatch (
  EnqueuedTime:datetime,
  Message:string,
  Application:string,
  Device:string,
  Simulated:boolean,
  Template:string,
  Module:string,
  Component:string,
  Capability:string,
  Value:dynamic
)

Nesse cenário, o dispositivo envia mensagens de telemetria que se parecem com o exemplo a seguir:

{
    "applicationId": "22223333-cccc-4444-dddd-5555eeee6666",
    "enqueuedTime": "1909-10-10T07:11:56.078161042Z",
    "messageSource": "telemetry",
    "telemetry": [
        {
            "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:HeartRate;1",
            "name": "HeartRate",
            "value": -633994413
        },
        {
            "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:RespiratoryRate;1",
            "name": "RespiratoryRate",
            "value": 1582211310
        },
        {
            "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:HeartRateVariability;1",
            "name": "HeartRateVariability",
            "value": -37514094
        },
        {
            "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:BodyTemperature;1",
            "name": "BodyTemperature",
            "value": 5.323322666478241e+307
        },
        {
            "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:FallDetection;1",
            "name": "FallDetection",
            "value": "Earum est nobis at voluptas id qui."
        },
        {
            "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_37p:BloodPressure;1",
            "name": "BloodPressure",
            "value": {
                "Diastolic": 161438124,
                "Systolic": -966387879
            }
        }
    ],
    "device": {
        "id": "9xwhr7khkfri",
        "name": "wireless port",
        "templateId": "dtmi:hpzy1kfcbt2:umua7dplmbd",
        "templateName": "Smart Vitals Patch",
        "properties": {
            "reported": [
                {
                    "id": "dtmi:smartVitalsPatch:Smart_Vitals_Patch_wr:DeviceStatus;1",
                    "name": "DeviceStatus",
                    "value": "Id optio iste vero et neque sit."
                }
            ]
        },
        "cloudProperties": [],
        "simulated": true,
        "approved": true,
        "blocked": false,
        "provisioned": false
    }
}

A consulta JQ a seguir transforma a mensagem de entrada em uma mensagem de saída separada para cada valor de telemetria. Essa transformação produz uma saída que corresponde ao esquema de tabela do Azure Data Explorer. A transformação usa um esquema entidade-atributo-valor em que cada linha contém um único valor de telemetria e o nome da telemetria é um valor em uma coluna separada na mesma linha:

. as $in | .telemetry[] | {
  EnqueuedTime: $in.enqueuedTime,
  Message: $in.messageId,
  Application: $in.applicationId,
  Device: $in.device.id,
  Simulated: $in.device.simulated,
  Template: ($in.device.templateName // ""),
  Module: ($in.module // ""),
  Component: ($in.component // ""),
  Capability: .name,
  Value: .value
}

Saída JSON:

{
  "Application": "22223333-cccc-4444-dddd-5555eeee6666",
  "Capability": "HeartRate",
  "Component": "",
  "Device": "9xwhr7khkfri",
  "EnqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "Message": null,
  "Module": "",
  "Simulated": true,
  "Template": "Smart Vitals Patch",
  "Value": -633994413
},
{
  "Application": "22223333-cccc-4444-dddd-5555eeee6666",
  "Capability": "RespiratoryRate",
  "Component": "",
  "Device": "9xwhr7khkfri",
  "EnqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "Message": null,
  "Module": "",
  "Simulated": true,
  "Template": "Smart Vitals Patch",
  "Value": 1582211310
},
{
  "Application": "22223333-cccc-4444-dddd-5555eeee6666",
  "Capability": "HeartRateVariability",
  "Component": "",
  "Device": "9xwhr7khkfri",
  "EnqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "Message": null,
  "Module": "",
  "Simulated": true,
  "Template": "Smart Vitals Patch",
  "Value": -37514094
},
{
  "Application": "22223333-cccc-4444-dddd-5555eeee6666",
  "Capability": "BodyTemperature",
  "Component": "",
  "Device": "9xwhr7khkfri",
  "EnqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "Message": null,
  "Module": "",
  "Simulated": true,
  "Template": "Smart Vitals Patch",
  "Value": 5.323322666478241e+307
},
{
  "Application": "22223333-cccc-4444-dddd-5555eeee6666",
  "Capability": "FallDetection",
  "Component": "",
  "Device": "9xwhr7khkfri",
  "EnqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "Message": null,
  "Module": "",
  "Simulated": true,
  "Template": "Smart Vitals Patch",
  "Value": "Earum est nobis at voluptas id qui."
},
{
  "Application": "22223333-cccc-4444-dddd-5555eeee6666",
  "Capability": "BloodPressure",
  "Component": "",
  "Device": "9xwhr7khkfri",
  "EnqueuedTime": "1909-10-10T07:11:56.078161042Z",
  "Message": null,
  "Module": "",
  "Simulated": true,
  "Template": "Smart Vitals Patch",
  "Value": {
      "Diastolic": 161438124,
      "Systolic": -966387879
  }
}

Os dados de saída são exportados para o cluster do Azure Data Explorer. Para visualizar os dados exportados no Power BI, conclua as seguintes etapas:

1. Instale o aplicativo Power BI. Você pode baixar o aplicativo Power BI da área de trabalho de Ir de dados para insights para ação com o Power BI Desktop.
2. Baixe o arquivo Power BI desktop IoT Central ADX Connector.pbit do GitHub.
3. Use o aplicativo Power BI Desktop para abrir o arquivo IoT Central ADX Connector.pbit que você baixou na etapa anterior. Quando solicitado, insira as informações de cluster, banco de dados e tabela do Azure Data Explorer que você anotou anteriormente.

Agora você pode visualizar os dados no Power BI:

Próximos passos

Agora que você já sabe como transformar dados no IoT Central, um próximo passo sugerido é aprender Como usar a análise no IoT Central.