Mapear telemetria na entrada para o IoT Central

O mapeamento de dados permite transformar a telemetria complexa do dispositivo 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 dispositivo e experiências de gerenciamento de dispositivo 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.

Dica

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

O seguinte vídeo orienta você no processo de mapeamento de dados:

Mapear telemetria para 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 de 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 IoT Central, escolha uma das seguintes opções para navegar até o painel Mapear dados:

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

  

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

  

O lado esquerdo do painel de Mapear dados mostra a mensagem mais recente do seu dispositivo. Passe o 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 até 64 caracteres. Você não pode usar o alias para se referir a um campo em um objeto complexo definido no modelo de dispositivo.

Adicione quantos mapeamentos forem necessários e, em seguida, selecione Salvar:

Para um determinado dispositivo:

• Nenhum mapeamento pode ter o mesmo caminho JSON de outro mapeamento.
• Nenhum mapeamento pode ter o mesmo alias de outro mapeamento.

Dica

Talvez seja necessário aguardar vários minutos para que seu 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 Caminho JSON.

Para verificar se o IoT Central está mapeando a telemetria, navegue até a exibição de Dados brutos para seu dispositivo e marque a seção _mappeddata:

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 do IoT Edge e do hub. 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 todos os dados do seu dispositivo antes de atribuí-los a um modelo de dispositivo.

Gerenciar mapeamentos

Para exibir, 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 seus dados.

Mapear telemetria não modelada

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

{
  "_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

Observação

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

Os resultados dessas regras de mapeamento são semelhantes aos 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.