Mapear telemetria em entrada para IoT Central

O mapeamento de dados permite transformar a telemetria complexa do dispositivo em dados estruturados dentro da IoT Central. Para cada um dos seus dispositivos, pode mapear um caminho JSON específico na mensagem de telemetria do dispositivo para um pseudónimo. Um pseudónimo é um nome amigável para o alvo a que estás a mapear. A IoT Central utiliza os mapeamentos para transformar a telemetria a caminho da IoT Central. Pode utilizar a telemetria mapeada para:

  • Crie modelos de dispositivos e experiências de gestão de dispositivos na IoT Central.
  • Normalize a telemetria de diferentes dispositivos mapeando caminhos JSON em vários dispositivos para um pseudónimo comum.
  • Exportar para destinos fora da IoT Central.

Diagrama que resume o processo de mapeamento na IoT Central.

O vídeo que se segue acompanha-o através do processo de mapeamento de dados:

Mapear telemetria para o seu dispositivo

Um mapeamento usa uma expressão JSONPath para identificar o valor numa mensagem de telemetria para mapear para um pseudónimo.

Uma expressão JSONPath começa com o $ personagem, que se refere ao elemento raiz da mensagem. Segue-se $ uma sequência de elementos infantis separados com suportes quadrados. Por exemplo:

$["messages"]["tmp"]

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

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

IoT Central utiliza um subconjunto da sintaxe de expressão JSONPath:

  • Cada segmento só pode ser um número não negativo ou uma corda fechada em aspas duplas.
  • Um segmento não pode conter backslash, suporte quadrado ou marcas de aspas duplas.
  • Um caminho JSON não pode exceder 1.000 caracteres.

Para criar um mapeamento na sua aplicação IoT Central, escolha uma das seguintes opções para navegar no painel de dados do Mapa :

  • A partir de qualquer página do dispositivo, selecione Gerir os dados do mapa do dispositivo>:

    Screenshot que mostra o item do menu **Mapa**

  • A partir da vista de dados Raw para o seu dispositivo, expanda qualquer mensagem de telemetria, passe o ponteiro do rato sobre um caminho e selecione Adicionar pseudónimo. O painel de dados do Mapa abre com a expressão JSONPath copiada para o campo de percurso JSON :

    Screenshot que mostra a opção **Add alias** na vista **Raw data**

O lado esquerdo do painel de dados do Mapa mostra a mensagem mais recente do seu dispositivo. Passe para o ponteiro do rato sobre qualquer parte dos dados e selecione Adicionar Alias. A expressão JSONPath é copiada para o caminho JSON. Adicione um nome Alias com não mais de 64 caracteres. Não é possível usar o pseudónimo para se referir a um campo num objeto complexo definido no modelo do dispositivo.

Adicione os mapeamentos que precisar e, em seguida, selecione Guardar:

Screenshot da vista **Map** mostrando o caminho e o pseudónimo Json.

Para um determinado dispositivo:

  • Não há dois mapeamentos que podem ter o mesmo caminho JSON.
  • Não há dois mapeamentos que possam ter o mesmo pseudónimo.

Dica

Pode ter de esperar vários minutos para que o seu dispositivo envie uma mensagem de telemetria para visualizar no painel da mão esquerda. Se ainda não houver dados no painel do lado esquerdo, pode introduzir manualmente uma expressão JSONPath no campo de caminhos JSON .

Para verificar se a IoT Central está a mapear a telemetria, navegue para a vista de dados Raw para o seu dispositivo e verifique a _mappeddata secção:

Screenshot que mostra a secção de dados mapeada numa mensagem na vista **Raw data**

Se não vir os seus dados mapeados depois de refrescar os dados Raw várias vezes, verifique se a expressão JSONPath que está a usar corresponde à estrutura da mensagem de telemetria.

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

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

Gerir mapeamentos

Para visualizar, editar ou eliminar mapeamentos, navegue para a página de pseudónimos Mapeados . Selecione um mapeamento para editar ou eliminá-lo. Pode selecionar vários mapeamentos e eliminá-los ao mesmo tempo:

Screenshot que mostra a vista **Mapped aliases** com os botões de edição e exclusão.

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

Telemetria não modelo

Pode mapear telemetria não modelo, incluindo telemetria de componentes não testados. Por exemplo, dada a workingSet telemetria definida no componente raiz e a temperature telemetria definida num componente do termóstato indicado 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"
}

Pode mapear esta telemetria utilizando 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 destas regras de mapeamento parecem 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 pode utilizar os pseudónimos mapeados para exibir telemetria num gráfico ou painel de instrumentos. Também pode usar os pseudónimos mapeados quando exportar telemetria.

Passos seguintes

Agora que aprendeu a mapear dados para o seu dispositivo, um próximo passo sugerido é aprender como usar o explorador de dados para analisar dados do dispositivo.