Mapeie a telemetria na entrada no IoT Central

O mapeamento de dados permite transformar a telemetria de dispositivos complexos em dados estruturados dentro do IoT Central. Para cada um dos seus dispositivos, você pode mapear um caminho JSON específico na mensagem de telemetria do dispositivo para um alias. Um alias é um nome amigável para o destino para o qual você está mapeando. O IoT Central usa os mapeamentos para transformar a telemetria no caminho para o IoT Central. Você pode usar a telemetria mapeada para:

• Crie modelos de dispositivos e experiências de gerenciamento de dispositivos no IoT Central.
• Normalize a telemetria de diferentes dispositivos mapeando caminhos JSON em vários dispositivos para um alias comum.
• Exporte para destinos fora do IoT Central.

Gorjeta

Se você quiser gerar automaticamente um modelo de dispositivo a partir de telemetria não modelada, consulte Gerar automaticamente um modelo de dispositivo.

O vídeo a seguir orienta você pelo processo de mapeamento de dados:

Mapear telemetria para o seu dispositivo

Um mapeamento usa uma expressão JSONPath para identificar o valor em uma mensagem de telemetria de entrada para mapear para um alias.

Uma expressão JSONPath começa com o $ caractere, que se refere ao elemento raiz da mensagem. O $ é seguido por uma sequência de elementos filho separados por colchetes. Por exemplo:

$["messages"]["tmp"]

$["opcua"]["payload"][0]["value"]

$["Messages"]["Payload"]["nsu=http://microsoft.com/Opc/OpcPlc/;s=FastUInt1"]["Value"]

O IoT Central usa um subconjunto da sintaxe da expressão JSONPath:

• Cada segmento só pode ser um número não negativo ou uma cadeia de caracteres entre aspas duplas.
• Um segmento não pode conter barra invertida, colchete ou aspas duplas.
• Um caminho JSON não pode exceder 1.000 caracteres.

Para criar um mapeamento em seu aplicativo IoT Central, escolha uma das seguintes opções para navegar até o painel Dados do mapa :

• Em qualquer página do dispositivo, selecione Gerenciar dados do mapa do dispositivo>:

  

• Na visualização Dados brutos do dispositivo, expanda qualquer mensagem de telemetria, passe o ponteiro do mouse sobre um caminho e selecione Adicionar alias. O painel Dados do mapa é aberto com a expressão JSONPath copiada para o campo de caminho JSON:

  

O lado esquerdo do painel Dados do mapa mostra a mensagem mais recente do seu dispositivo. Passe o ponteiro do mouse sobre qualquer parte dos dados e selecione Adicionar alias. A expressão JSONPath é copiada para o caminho JSON. Adicione um nome de alias com no máximo 64 caracteres. Não é possível usar o alias para fazer referência a um campo em um objeto complexo definido no modelo de dispositivo.

Adicione quantos mapeamentos precisar e selecione Salvar:

Para um determinado dispositivo:

• Não há dois mapeamentos que possam ter o mesmo caminho JSON.
• Não há dois mapeamentos que possam ter o mesmo alias.

Gorjeta

Pode ser necessário aguardar vários minutos para que o dispositivo envie uma mensagem de telemetria para exibição no painel esquerdo. Se ainda não houver dados no painel esquerdo, você poderá inserir manualmente uma expressão JSONPath no campo de caminho JSON.

Para verificar se o IoT Central está mapeando a telemetria, navegue até a visualização de dados brutos do seu dispositivo e verifique a _mappeddata seção:

Se você não vir os dados mapeados depois de atualizar os dados brutos várias vezes, verifique se a expressão JSONPath que você está usando corresponde à estrutura da mensagem de telemetria.

Para dispositivos IoT Edge, o mapeamento de dados se aplica à telemetria de todos os módulos e hub do IoT Edge. Não é possível aplicar mapeamentos a um módulo específico do Azure IoT Edge.

Para dispositivos atribuídos a um modelo de dispositivo, não é possível mapear dados para componentes ou interfaces herdadas. No entanto, você pode mapear quaisquer dados do seu dispositivo antes de atribuí-los a um modelo de dispositivo.

Gerenciar mapeamentos

Para visualizar, editar ou excluir mapeamentos, navegue até a página Aliases mapeados. Selecione um mapeamento para editá-lo ou excluí-lo. Você pode selecionar vários mapeamentos e excluí-los ao mesmo tempo:

Por padrão, as exportações de dados do IoT Central incluem dados mapeados. Para excluir dados mapeados, use uma transformação de dados na exportação de dados.

Mapear telemetria não modelada

Você pode mapear telemetria não modelada, incluindo telemetria de componentes não modelados. Por exemplo, dada a telemetria workingSet definida no componente raiz e a telemetria temperature definida em um componente termostato mostrado no exemplo a seguir:

{
  "_unmodeleddata": {
    "workingSet": 74
  },
  "_eventtype": "Telemetry",
  "_timestamp": "2022-07-18T09:22:40.257Z"
}

{
  "_unmodeleddata": {
    "thermostat2": {
      "__t": "c",
      "temperature": 44
    }
  },
  "_eventtype": "Telemetry",
  "_timestamp": "2022-07-18T09:21:48.69Z"
}

Você pode mapear essa telemetria usando as seguintes definições de mapeamento:

• $["workingSet"] ws
• $["temperature"] temp

Nota

Não inclua o nome do componente na definição de mapeamento.

Os resultados dessas regras de mapeamento se parecem com os seguintes exemplos:

{
  "telemetries": {
    "workingSet": 84,
    "_mappeddata": {
      "ws": 84
    }
  }
}

{
  "_unmodeleddata": {
    "thermostat2": {
      "__t": "c",
      "temperature": 12
    },
    "_mappeddata": {
      "thermostat2": {
        "__t": "c",
        "temp": 12
      }
    }
  },
  "_eventtype": "Telemetry",
  "_timestamp": "2022-07-18T09:31:21.088Z"
}

Agora você pode usar os aliases mapeados para exibir a telemetria em um gráfico ou painel. Você também pode usar os aliases mapeados ao exportar telemetria.