Transformar dados com mapeamento em gráficos de fluxo de dados

No Operações IoT do Azure, uma transformação de mapa pega em cada mensagem recebida num gráfico de fluxo de dados e produz uma mensagem de saída baseada nas suas regras. Podes renomear campos, reorganizá-los em novas estruturas, calcular valores derivados ou remover campos indesejados. Ao usar regras de curinga, pode copiar todos os campos de uma só vez.

Para uma visão geral dos gráficos de fluxo de dados e de como as transformações se compõem num pipeline, consulte Visão Geral dos Gráficos de Fluxo de Dados.

As transformações utilizam uma linguagem de expressões para calcular valores, condições de teste e campos de referência. Expressões referem-se a entradas por posição, não pelo nome: a primeira entrada na inputs lista é $1, a segunda é $2, e assim sucessivamente. Funções incorporadas como cToF convertem e manipulam esses valores.

Para a lista completa de operadores, funções, tipos de dados e campos de metadados, consulte a referência Expressões.

Pré-requisitos

Uma instância do Operações IoT do Azure implementada num cluster Kubernetes. Para mais informações, consulte Deploy Operações IoT do Azure.

Um endpoint de registo predefinido chamado default que aponta mcr.microsoft.com é criado automaticamente durante a implementação. As transformações incorporadas usam este endpoint.

Os CLI do Azure exemplos deste artigo usam variáveis de ambiente para que possas definir cada valor uma vez e depois copiar e colar os comandos as-is. Se estiver a usar o ambiente Operações IoT do Azure Codespaces do quickstart, estas variáveis já estão definidas para si e pode saltar este passo. Caso contrário, defina as seguintes variáveis de ambiente no seu shell antes de executar os comandos.

Os seguintes scripts definem as variáveis de ambiente mais usadas:

Variável de ambiente	Descrição
`SUBSCRIPTION_ID`	O ID da subscrição que contém a sua instância Operações IoT do Azure.
`RESOURCE_GROUP`	O nome do grupo de recursos que contém a sua instância do Operações IoT do Azure.
`AIO_INSTANCE_NAME`	O nome da sua instância do Operações IoT do Azure. Para listar as suas instâncias, execute `az iot ops list -o table`.
`CLUSTER_NAME`	O nome do cluster Kubernetes com Azure Arc que hospeda a sua instância.
`LOCATION`	A região do Azure deve ser usada para novos recursos, por exemplo `eastus`.

Bash
PowerShell

SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

$SUBSCRIPTION_ID = "<subscription-id>"
$RESOURCE_GROUP = "<resource-group-name>"
$AIO_INSTANCE_NAME = "<instance-name>"
$CLUSTER_NAME = "<cluster-name>"
$LOCATION = "<region>"

Só precisa de definir as variáveis que este artigo utiliza. Este artigo pode usar variáveis adicionais de ambiente para nomes de recursos que escolher. O artigo explica como posicioná-los onde são apresentados.

Como funcionam as regras do mapa

Cada regra de mapa tem quatro partes:

Propriedade	Obrigatório	Descrição
`inputs`	Sim	Lista de caminhos de campo a ler da mensagem recebida.
`output`	Sim	Caminho de campo onde o resultado aparece na mensagem de saída.
`expression`	No	Fórmula aplicada aos valores de entrada. Se o omitir, o valor da primeira entrada é copiado diretamente.
`description`	No	Rótulo legível por humanos para a regra, incluído em mensagens de erro.

A transformada de aplicação atribui variáveis posicionais às entradas por ordem. Por exemplo, se inputs é , então ['Position', 'Office'] é o valor de $1 e Position é o valor de $2Office.

Renomear um campo

Para renomear BirthDate para DateOfBirth, mapeia uma entrada para um caminho de saída diferente. Não precisas de expressão. O valor é copiado tal como está.

Na configuração de transformação do mapa, adicione uma regra:

Configuração	Value
Input	`BirthDate`
Output	`DateOfBirth`

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "BirthDate"
  ],
  "output": "DateOfBirth"
}

{
  inputs: [
    'BirthDate'
  ]
  output: 'DateOfBirth'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - BirthDate
  output: DateOfBirth

Reestruturação de campos

Use notação de pontos no caminho de saída para mover campos para uma estrutura aninhada.

Adicione duas regras:

Entrada	Output
`Name`	`Employee.Name`
`BirthDate`	`Employee.DateOfBirth`

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "Name"
  ],
  "output": "Employee.Name"
},
{
  "inputs": [
    "BirthDate"
  ],
  "output": "Employee.DateOfBirth"
}

{
  inputs: [ 'Name' ]
  output: 'Employee.Name'
}
{
  inputs: [ 'BirthDate' ]
  output: 'Employee.DateOfBirth'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - Name
  output: Employee.Name

- inputs:
    - BirthDate
  output: Employee.DateOfBirth

Dado este input:

{
  "Name": "Grace Owens",
  "BirthDate": "19840202",
  "Position": "Analyst"
}

Estas duas regras produzem:

{
  "Employee": {
    "Name": "Grace Owens",
    "DateOfBirth": "19840202"
  }
}

Apenas os campos listados na saída de uma regra aparecem no resultado. O resultado não inclui o Position campo porque nenhuma regra o mapeia.

Combinar múltiplas entradas

Quando listar múltiplas entradas, use as variáveis posicionais delas para as fundir numa expressão.

Adicionar uma regra:

Configuração	Value
Entradas	`Position`, `Office`
Output	`Employment.Position`
Expressão	`$1 + ", " + $2`

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "Position",
    "Office"
  ],
  "output": "Employment.Position",
  "expression": "$1 + \", \" + $2"
}

{
  inputs: [ 'Position', 'Office' ]
  output: 'Employment.Position'
  expression: '$1 + ", " + $2'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - Position     # $1
    - Office       # $2
  output: Employment.Position
  expression: "$1 + \", \" + $2"

Dado Position: "Analyst" e Office: "Kent, WA", a saída é "Analyst, Kent, WA".

Transforme valores com expressões

Use o expression campo para aplicar funções ou aritmética incorporadas. O exemplo seguinte utiliza cToF, uma função de conversão unitária incorporada que converte um valor Celsius em Fahrenheit. Lembre-se que isso $1 se refere à primeira entrada, não a um nome de campo.

Para a lista completa de operadores, funções e funcionalidades avançadas, consulte a referência Expressões. A referência agrupa funções por categoria, como conversão de unidades, escala e arredondamento, matemática e funções de cadeia .

Adiciona uma regra de computação. Por exemplo, para converter Celsius em Fahrenheit:

Configuração	Value
Input	`temperature`
Output	`temperature_f`
Expressão	`cToF($1)`

Para escalar uma leitura de sensor para um intervalo de 0 a 100, use a expressão scale($1, 0, 4095, 0, 100).

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "temperature"
  ],
  "output": "temperature_f",
  "expression": "cToF($1)"
}

Para escalar uma leitura de sensor:

{
  "inputs": [
    "raw_pressure"
  ],
  "output": "pressure_pct",
  "expression": "scale($1, 0, 4095, 0, 100)"
}

{
  inputs: [ 'temperature' ]
  output: 'temperature_f'
  expression: 'cToF($1)'
}

Para escalar uma leitura de sensor:

{
  inputs: [ 'raw_pressure' ]
  output: 'pressure_pct'
  expression: 'scale($1, 0, 4095, 0, 100)'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - temperature     # $1
  output: temperature_f
  expression: "cToF($1)"

Para escalar uma leitura de sensor:

- inputs:
    - raw_pressure     # $1
  output: pressure_pct
  expression: "scale($1, 0, 4095, 0, 100)"

Copiar todos os campos com caracteres universais

Quando a saída deve corresponder de perto à entrada com apenas algumas alterações, use uma regra curinga para copiar todos os campos de uma só vez. Depois adiciona regras para sobrepor, adicionar ou remover campos específicos.

Adiciona uma regra de passthrough que copia todos os campos. Defina a entrada para * e a saída para *.

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "*"
  ],
  "output": "*"
}

{
  inputs: [ '*' ]
  output: '*'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - '*'
  output: '*'

Requisitos da regra do wildcard

Uma regra coringa deve ser a primeira regra na configuração do mapa.
Uma transformação de mapa suporta apenas uma regra de coringa.
O asterisco corresponde a um ou mais segmentos de caminho e deve representar um segmento completo. A transformação do mapa não suporta padrões parciais como partial*.

Curingas de prefixo

Define o coringa com um prefixo específico. Para achatar todos os campos de ColorProperties para o nível raiz:

Adicione uma regra com entrada ColorProperties.* e saída *.

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "ColorProperties.*"
  ],
  "output": "*"
}

{
  inputs: [ 'ColorProperties.*' ]
  output: '*'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - 'ColorProperties.*'
  output: '*'

Dado:

{
  "ColorProperties": {
    "Hue": "blue",
    "Saturation": "90%",
    "Brightness": "50%"
  }
}

A saída é:

{
  "Hue": "blue",
  "Saturation": "90%",
  "Brightness": "50%"
}

Remover campos da saída

Defina o output para uma cadeia vazia para excluir campos específicos. Normalmente, usa esta abordagem após uma regra coringa: copia tudo e depois remove o que não precisas.

Adicione uma regra de passthrough para copiar todos os campos.
Adicione uma regra de remoção e selecione os campos a excluir (por exemplo, password e internal_id).

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "*"
  ],
  "output": "*"
},
{
  "inputs": [
    "password",
    "internal_id"
  ],
  "output": ""
}

{
  inputs: [ '*' ]
  output: '*'
}
{
  inputs: [ 'password', 'internal_id' ]
  output: ''
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - '*'
  output: '*'

- inputs:
    - password
    - internal_id
  output: ""

Uma regra de remoção não pode incluir uma expressão.

Anule os curingas para campos específicos

Quando uma regra de wildcard e uma regra específica coincidem ambas no mesmo campo, a regra mais específica tem prioridade.

Adicione uma regra de passthrough para copiar todos os campos.
Adicione uma regra de cálculo para temperature com a expressão cToF($1).

A transformação do mapa aplica a regra específica a temperature e copia todos os outros campos da forma como está.

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "*"
  ],
  "output": "*"
},
{
  "inputs": [
    "temperature"
  ],
  "output": "temperature",
  "expression": "cToF($1)"
}

{
  inputs: [ '*' ]
  output: '*'
}
{
  inputs: [ 'temperature' ]
  output: 'temperature'
  expression: 'cToF($1)'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - '*'
  output: '*'

- inputs:
    - temperature     # $1
  output: temperature
  expression: "cToF($1)"

Utilizar campos de metadados

Leia e escreva para metadados de mensagens, como tópicos MQTT e propriedades do utilizador. Consulte os campos de metadados na referência de expressões.

Adicione uma regra com entrada region e saída $metadata.user_property.region para escrever um valor de campo numa propriedade de utilizador MQTT.

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "*"
  ],
  "output": "*"
},
{
  "inputs": [
    "region"
  ],
  "output": "$metadata.user_property.region"
}

{
  inputs: [ '*' ]
  output: '*'
}
{
  inputs: [ 'region' ]
  output: '$metadata.user_property.region'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - '*'
  output: '*'

- inputs:
    - region
  output: $metadata.user_property.region

Para um exemplo completo de encaminhamento dinâmico por tópicos, veja Encaminhar mensagens para diferentes tópicos.

Usar o último valor conhecido e as predefinições

Quando os dados dos sensores chegam intermitentemente, pode preencher campos em falta com o último valor conhecido ou um padrão estático. Veja Último valor conhecido e valores padrão na referência de expressões.

Adicione uma regra para o temperature campo e ative o Último valor conhecido. Defina um valor padrão de 0 como alternativa.

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "temperature ? $last ?? 0"
  ],
  "output": "temperature"
}

{
  inputs: [ 'temperature ? $last ?? 0' ]
  output: 'temperature'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - temperature ? $last ?? 0     # $1
  output: temperature

Esta regra usa o valor atual quando presente, volta ao último valor conhecido e usa 0 se nenhum estiver disponível.

Enriquecer com dados externos

O enriquecimento é opcional. Só precisa disso se quiser combinar mensagens recebidas com dados de referência armazenados no armazenamento de estado, como uma tabela de pesquisa com metadados dos dispositivos. Se as tuas mensagens já contêm tudo o que precisas, salta esta secção.

Quando precisares de enriquecimento, configura um conjunto de dados de contextualização que o runtime consulta durante o processamento. Por exemplo, procure os metadados de um dispositivo pelo seu ID e inclua-os na saída. Para detalhes, consulte Enriquecer com dados externos.

Funcionalidades exclusivas dos grafos de fluxo de dados

Os gráficos de fluxo de dados suportam várias funcionalidades que não estão disponíveis nos mapeamentos de fluxo builtInTransformation de dados.

Valores padrão para campos em falta

Utilize a sintaxe ?? <default> num input para fornecer um plano de recurso estático quando um campo está ausente. Isto é mais simples do que escrever uma if expressão para verificar valores vazios.

Na configuração de transformação de mapa, configure a entrada para incluir a sintaxe ?? seguida do valor padrão. Por exemplo, introduzir temperature ?? 0 como o campo de entrada a ser usado 0 quando o campo de temperatura estiver em falta.

A CLI aplica o grafo completo a partir de um ficheiro de configuração, por isso adiciona isto no local correspondente do teu graph.json e aplica-o com az iot ops dataflowgraph apply:

{
  "inputs": [
    "temperature ?? 0"
  ],
  "output": "temperature"
}

{
  inputs: [ 'temperature ?? 0' ]
  output: 'temperature'
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

- inputs:
    - temperature ?? 0
  output: temperature

Para detalhes sobre tipos padrão suportados e a combinação de valores padrão com os últimos valores conhecidos, veja Valores padrão na referência de expressões.

Funções Regex

Os grafos de fluxo de dados suportam correspondência e substituição de expressões regulares:

str::regex_matches(string, pattern): Retorna verdadeiro se a cadeia coincidir com o padrão regex.
str::regex_replace(string, pattern, replacement): Substitui todas as correspondências de expressões regulares pela string de substituição.

Estas funções são úteis em expressões de filtro ou para limpar e transformar dados de cadeias. Para a lista completa de funções de cadeia, veja Funções de cadeia na referência de expressões.

Exemplo completo de configuração

Aqui está uma configuração completa do mapa que copia todos os campos, remove dados sensíveis, reestrutura um campo e calcula um valor derivado:

Captura de ecrã do painel de configuração da transformação do mapa de experiência de operações mostrando múltiplas regras para wildcard, remover, reestruturar, calcular e mesclar.

Na experiência de Operações, crie um gráfico de fluxo de dados e adicione uma transformação de mapa. No painel de configuração do mapa, adicione regras a:

Copie todos os campos com um passthrough coringa.
Remover campos sensíveis definindo a saída para vazia para password e secret_key.
Reestruturar o BirthDate corpo para Employee.DateOfBirth.
Calcule uma conversão Fahrenheit usando a fórmula cToF($1) no temperature campo.
Mescle os campos Position e Office com a fórmula $1 + ", " + $2.

A CLI do Azure aplica um grafo de fluxo de dados a partir de um único ficheiro de configuração JSON. Cria um graph.json ficheiro com as propriedades do grafo. No graph.json ficheiro, o value campo armazena as regras de cada transformação como uma string JSON escapada. Para a forma legível das regras de cada transformação, veja o tutorial para esse tipo de transformação.

{
  "mode": "Enabled",
  "nodes": [
    {
      "nodeType": "Source",
      "name": "sensors",
      "sourceSettings": {
        "endpointRef": "default",
        "dataSources": [
          "telemetry/sensors"
        ]
      }
    },
    {
      "nodeType": "Graph",
      "name": "transform",
      "graphSettings": {
        "registryEndpointRef": "default",
        "artifact": "azureiotoperations/graph-dataflow-map:1.0.0",
        "configuration": [
          {
            "key": "rules",
            "value": "{\"map\":[{\"inputs\":[\"*\"],\"output\":\"*\",\"description\":\"Copy all fields\"},{\"inputs\":[\"password\",\"secret_key\"],\"output\":\"\",\"description\":\"Remove sensitive fields\"},{\"inputs\":[\"BirthDate\"],\"output\":\"Employee.DateOfBirth\",\"description\":\"Restructure birth date\"},{\"inputs\":[\"temperature\"],\"output\":\"temperature_f\",\"expression\":\"cToF($1)\",\"description\":\"Convert Celsius to Fahrenheit\"},{\"inputs\":[\"Position\",\"Office\"],\"output\":\"Employment.Position\",\"expression\":\"$1 + \\\", \\\" + $2\",\"description\":\"Merge position and office\"}]}"
          }
        ]
      }
    },
    {
      "nodeType": "Destination",
      "name": "output",
      "destinationSettings": {
        "endpointRef": "default",
        "dataDestination": "telemetry/processed"
      }
    }
  ],
  "nodeConnections": [
    {
      "from": {
        "name": "sensors"
      },
      "to": {
        "name": "transform"
      }
    },
    {
      "from": {
        "name": "transform"
      },
      "to": {
        "name": "output"
      }
    }
  ]
}

Sugestão

Para gerar a string escapada, guarde as regras num ficheiro como rules.json, execute jq -c . rules.json, e cole a saída de linha única no value campo.

Aplica o ficheiro de configuração.

az iot ops dataflowgraph apply \
  --name temperature-map-example \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --config-file graph.json

resource dataflowGraph 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflowGraphs@2026-03-01' = {
  name: 'temperature-map-example'
  parent: dataflowProfile
  properties: {
    mode: 'Enabled'
    nodes: [
      {
        nodeType: 'Source'
        name: 'sensors'
        sourceSettings: {
          endpointRef: 'default'
          dataSources: [
            'telemetry/sensors'
          ]
        }
      }
      {
        nodeType: 'Graph'
        name: 'transform'
        graphSettings: {
          registryEndpointRef: 'default'
          artifact: 'azureiotoperations/graph-dataflow-map:1.0.0'
          configuration: [
            {
              key: 'rules'
              value: '{"map":[{"inputs":["*"],"output":"*","description":"Copy all fields"},{"inputs":["password","secret_key"],"output":"","description":"Remove sensitive fields"},{"inputs":["BirthDate"],"output":"Employee.DateOfBirth","description":"Restructure birth date"},{"inputs":["temperature"],"output":"temperature_f","expression":"cToF($1)","description":"Convert Celsius to Fahrenheit"},{"inputs":["Position","Office"],"output":"Employment.Position","expression":"$1 + \\", \\" + $2","description":"Merge position and office"}]}'
            }
          ]
        }
      }
      {
        nodeType: 'Destination'
        name: 'output'
        destinationSettings: {
          endpointRef: 'default'
          dataDestination: 'telemetry/processed'
        }
      }
    ]
    nodeConnections: [
      {
        from: { name: 'sensors' }
        to: { name: 'transform' }
      }
      {
        from: { name: 'transform' }
        to: { name: 'output' }
      }
    ]
  }
}

Importante

A utilização dos manifestos de implementação do Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

A configuração das regras é uma string JSON colocada como value para a chave rules na secção DataflowGraph de um nó de transformação configuration.

{
  "map": [
    {
      "inputs": ["*"],
      "output": "*",
      "description": "Copy all fields"
    },
    {
      "inputs": ["password", "secret_key"],
      "output": "",
      "description": "Remove sensitive fields"
    },
    {
      "inputs": ["BirthDate"],
      "output": "Employee.DateOfBirth",
      "description": "Restructure birth date"
    },
    {
      "inputs": ["temperature"],
      "output": "temperature_f",
      "expression": "cToF($1)",
      "description": "Convert Celsius to Fahrenheit"
    },
    {
      "inputs": ["Position", "Office"],
      "output": "Employment.Position",
      "expression": "$1 + \", \" + $2",
      "description": "Merge position and office"
    }
  ]
}

Para a estrutura completa DataflowGraph de recursos, consulte a visão geral dos gráficos de fluxo de dados.

Comentários

Esta página foi útil?

Last updated on 2026-07-31

Transformar dados com mapeamento em gráficos de fluxo de dados

Pré-requisitos

Como funcionam as regras do mapa

Renomear um campo

Reestruturação de campos

Combinar múltiplas entradas

Transforme valores com expressões

Copiar todos os campos com caracteres universais

Requisitos da regra do wildcard

Curingas de prefixo

Remover campos da saída

Anule os curingas para campos específicos

Utilizar campos de metadados

Usar o último valor conhecido e as predefinições

Enriquecer com dados externos

Funcionalidades exclusivas dos grafos de fluxo de dados

Valores padrão para campos em falta

Funções Regex

Exemplo completo de configuração

Conteúdo relacionado

Comentários

Recursos adicionais