Transformar dados com mapa em grafos de fluxo de dados

No Operações do Azure IoT, uma transformada de mapa pega cada mensagem recebida em um gráfico de fluxo de dados e produz uma mensagem de saída baseada nas suas regras. Você pode renomear campos, reorganizar-os em novas estruturas, calcular valores derivados ou remover campos indesejados. Usando regras de curinga, você pode copiar todos os campos de uma vez.

Para obter uma visão geral dos grafos de fluxo de dados e como as transformações compõem em um pipeline, consulte a visão geral dos grafos de fluxo de dados.

Transformadas usam uma linguagem de expressão 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 por diante. Funções integradas como cToF convertem e manipulam esses valores.

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

Pré-requisitos

Uma instância de Operações do Azure IoT implantada em um cluster do Kubernetes. Para obter mais informações, consulte Deploy Operações do Azure IoT.

Um endpoint padrão chamado default que aponta para mcr.microsoft.com é criado automaticamente durante a implantação. As transformações integradas utilizam este ponto de extremidade.

Os CLI do Azure exemplos deste artigo usam variáveis de ambiente para que você possa definir cada valor uma vez e então copiar e colar os comandos as-is. Se você está usando o ambiente Operações do Azure IoT Codespaces do quickstart, essas variáveis já estão definidas para você e você pode pular essa etapa. 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 comumente usadas:

Variável de ambiente	Descrição
`SUBSCRIPTION_ID`	O ID da assinatura que contém sua instância do Operações do Azure IoT.
`RESOURCE_GROUP`	O nome do grupo de recursos que contém sua instância do Operações do Azure IoT.
`AIO_INSTANCE_NAME`	O nome da sua instância do Operações do Azure IoT. Para listar suas instâncias, execute `az iot ops list -o table`.
`CLUSTER_NAME`	O nome do cluster Kubernetes habilitado para Azure Arc que hospeda sua instância.
`LOCATION`	A região Azure para usar 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>"

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

Como funcionam as regras de mapa

Cada regra de mapa tem quatro partes:

Propriedade	Obrigatório	Descrição
`inputs`	Sim	Lista de caminhos de campos a serem lidos na 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 você omitir, o valor da primeira entrada é copiado diretamente.
`description`	No	Rótulo legível para a regra, incluído nas mensagens de erro.

A transformada de mapa atribui variáveis posicionais às entradas em 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, mapeie uma entrada para um caminho de saída diferente. Você não precisa de expressão. O valor é copiado tal como está.

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

Configurações	Valor
Input	`BirthDate`
Output	`DateOfBirth`

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-o com az iot ops dataflowgraph apply:

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

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

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

- inputs:
    - BirthDate
  output: DateOfBirth

Reestruturar campos

Use a notação de pontos no caminho de saída para organizar os campos em uma estrutura aninhada.

Adicione duas regras:

Entrada	Saída
`Name`	`Employee.Name`
`BirthDate`	`Employee.DateOfBirth`

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-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

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

- inputs:
    - Name
  output: Employee.Name

- inputs:
    - BirthDate
  output: Employee.DateOfBirth

Considerando esta entrada:

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

Essas duas regras produzem:

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

Somente 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 várias entradas

Quando você lista múltiplas entradas, use suas variáveis posicionais para fundi-las em uma expressão.

Adicionar uma regra:

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

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-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

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

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

Transformar valores com expressões

Use o expression campo para aplicar funções internas ou aritméticas. O exemplo a seguir usa cToF, uma função de conversão unitária embutida que converte um valor Celsius em Fahrenheit. Lembre-se que isso $1 se refere à primeira entrada, não ao nome do campo.

Para obter a lista completa de operadores, funções e recursos avançados, consulte a referência de expressões. A referência agrupa funções por categoria, como conversão de unidades, escala e arredondamento, matemática e funções de string .

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

Configurações	Valor
Input	`temperature`
Output	`temperature_f`
Expressão	`cToF($1)`

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

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-o com az iot ops dataflowgraph apply:

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

Para dimensionar 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 dimensionar uma leitura de sensor:

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

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

Para dimensionar uma leitura de sensor:

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

Copiar todos os campos com caracteres curinga

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. Em seguida, adicione regras para substituir, adicionar ou remover campos específicos.

Adicione uma regra de passagem que copia todos os campos. Defina a entrada * e a saída como *.

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-o com az iot ops dataflowgraph apply:

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

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

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

Requisitos para regra curinga

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

Caracteres curinga de prefixo

Defina o coringa com um prefixo específico. Para nivelar todos os campos do ColorProperties ao nível raiz:

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

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-o com az iot ops dataflowgraph apply:

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

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

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

Considerando-se:

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

A saída é:

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

Remover campos da saída

Defina o output como uma string vazia para excluir campos específicos. Normalmente, use essa abordagem após uma regra coringa: copie tudo e remova o que não precisa.

Adicione uma regra de passagem para copiar todos os campos.
Adicione uma regra de remoção e selecione os campos a serem excluídos (por exemplo, password e internal_id).

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-o com az iot ops dataflowgraph apply:

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

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

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

- inputs:
    - password
    - internal_id
  output: ""

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

Substituir caracteres curinga para campos específicos

Quando uma regra com curinga e uma regra específica correspondem ao mesmo campo, a regra mais específica tem precedência.

Adicione uma regra de passagem para copiar todos os campos.
Adicione uma regra de computação 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 tal como estão.

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-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

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

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

Usar campos de metadados

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

Adicione uma regra com entrada region e saída $metadata.user_property.region para gravar um valor de campo em uma propriedade de usuário MQTT.

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-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

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

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

Para obter um exemplo completo de roteamento de tópico dinâmico, consulte Encaminhar mensagens para tópicos diferentes.

Usar o último valor conhecido e valores padrão

Quando os dados do sensor chegam intermitentemente, você pode preencher campos ausentes com o último valor conhecido ou um padrão estático. Consulte o último valor conhecido e valores padrão na referência de expressões.

Adicione uma regra para o temperature campo e habilite o último valor conhecido. Defina um valor padrão como fallback de 0.

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-o com az iot ops dataflowgraph apply:

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

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

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

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

Essa regra usa o valor atual quando presente, volta para o último valor conhecido e usa 0 se nenhum dos dois estiver disponível.

Enriquecer com dados externos

Enriquecimento é opcional. Você só precisa dela se quiser combinar mensagens recebidas com dados de referência armazenados no estoque de estados, como uma tabela de consulta com metadados de dispositivos. Se suas mensagens já contêm tudo o que você precisa, pule esta seção.

Quando precisar de enriquecimento, configure um conjunto de dados de contextualização que o runtime consulte durante o processamento. Por exemplo, procure os metadados de um dispositivo por sua ID e inclua-os na saída. Para obter detalhes, consulte Enriquecer com dados externos.

Recursos exclusivos do grafo de fluxo de dados

Os grafos de fluxo de dados dão suporte a vários recursos que não estão disponíveis em mapeamentos de fluxo builtInTransformation de dados.

Valores padrão para campos ausentes

Use a sintaxe ?? <default> em um campo de entrada para fornecer um fallback estático quando um campo estiver ausente. Isso é mais simples do que escrever uma if expressão para verificar se há valores vazios.

Na configuração de transformação do mapa, defina a entrada para incluir a sintaxe ?? seguida pelo valor padrão. Por exemplo, insira temperature ?? 0 como o campo de entrada a ser usado 0 quando o campo de temperatura estiver ausente.

A CLI aplica todo o grafo de um arquivo de configuração, portanto, adicione-o ao local correspondente em seu graph.json e aplique-o com az iot ops dataflowgraph apply:

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

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

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

- inputs:
    - temperature ?? 0
  output: temperature

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

Funções regex

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

str::regex_matches(string, pattern): retorna true se a cadeia de caracteres corresponder ao padrão regex.
str::regex_replace(string, pattern, replacement): substitui todas as correspondências regex pela cadeia de caracteres de substituição.

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

Exemplo de configuração completa

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

Captura de tela do painel de configuração de transformação do mapa de experiência de operações, mostrando várias regras para curinga, remoção, reestruturação, cálculo e fusão.

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 uma passagem curinga.
Remova campos confidenciais definindo a saída como vazia para password e secret_key.
Reestruturar o BirthDate campo para Employee.DateOfBirth.
Calcule uma conversão Fahrenheit usando a fórmula cToF($1) no temperature campo.
Mesclar os campos Position e Office com a fórmula $1 + ", " + $2.

O CLI do Azure aplica um grafo de fluxo de dados de um único arquivo de configuração JSON. Crie um graph.json arquivo com as propriedades do grafo. No graph.json arquivo, o value campo armazena as regras de cada transformação como uma string JSON escapada. Para obter a forma legível das regras de cada transformação, consulte o instruções 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"
      }
    }
  ]
}

Dica

Para gerar a string escapada, salve as regras em um arquivo como rules.json, execute jq -c . rules.json e cole a saída em uma única linha no campo value.

Aplique o arquivo 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

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

A configuração de regras é uma cadeia de caracteres JSON colocada como value para a chave rules na seção do nó de DataflowGraph 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 obter a estrutura de recursos completa DataflowGraph , consulte a visão geral dos grafos de fluxo de dados.

Comentários

Esta página foi útil?

Last updated on 2026-07-31

Transformar dados com mapa em grafos de fluxo de dados

Pré-requisitos

Como funcionam as regras de mapa

Renomear um campo

Reestruturar campos

Combinar várias entradas

Transformar valores com expressões

Copiar todos os campos com caracteres curinga

Requisitos para regra curinga

Caracteres curinga de prefixo

Remover campos da saída

Substituir caracteres curinga para campos específicos

Usar campos de metadados

Usar o último valor conhecido e valores padrão

Enriquecer com dados externos

Recursos exclusivos do grafo de fluxo de dados

Valores padrão para campos ausentes

Funções regex

Exemplo de configuração completa

Conteúdo relacionado

Comentários

Recursos adicionais