Transformera data med karta i dataflödesdiagram

I Azure IoT Operations tar en karttransform varje inkommande meddelande i en dataflödesgraf och producerar ett utdatameddelande baserat på dina regler. Du kan byta namn på fält, omorganisera dem till nya strukturer, beräkna härledda värden eller ta bort oönskade fält. Genom att använda wildcard-regler kan du kopiera alla fält samtidigt.

En översikt över dataflödesdiagram och hur transformeringar består i en pipeline finns i Översikt över dataflödesdiagram.

Transformer använder ett uttrycksspråk för att beräkna värden, testvillkor och referensfält. Uttryck hänvisar till indata efter position, inte namn: den första indatan i inputs listan är $1, den andra är $2, och så vidare. Inbyggda funktioner som cToF konvertera och manipulera dessa värden.

För den fullständiga listan över operatorer, funktioner, datatyper och metadatafält, se referensen Expressions.

Förutsättningar

En instans av Azure IoT Operations distribuerad i ett Kubernetes-kluster. Mer information finns i Deploy Azure IoT Operations.

En standardregisterslutpunkt med namnet default som pekar mcr.microsoft.com på skapas automatiskt under distributionen. De inbyggda transformeringarna använder den här slutpunkten.

De Azure CLI exemplen i denna artikel använder miljövariabler så att du kan sätta varje värde en gång och sedan kopiera och klistra in kommandona as-is. Om du använder Azure IoT Operations Codespaces-miljön från quickstart är dessa variabler redan inställda för dig och du kan hoppa över detta steg. Annars, ställ in följande miljövariabler i ditt skal innan du kör kommandona.

Följande skript anger de mest använda miljövariablerna:

Miljövariabel	Beskrivning
`SUBSCRIPTION_ID`	ID:t för prenumerationen som innehåller din Azure IoT Operations-instans.
`RESOURCE_GROUP`	Namnet på resursgruppen som innehåller din Azure IoT Operations-instans.
`AIO_INSTANCE_NAME`	Namnet på din Azure IoT Operations-instans. För att lista dina instanser, kör `az iot ops list -o table`.
`CLUSTER_NAME`	Namnet på det Azure Arc-aktiverade Kubernetes-klustret som hostar din instans.
`LOCATION`	Azure-regionen att använda för nya resurser, till exempel `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>"

Du behöver bara ställa in de variabler som denna artikel använder. Den här artikeln kan använda ytterligare miljövariabler för resursnamn som du väljer. Artikeln förklarar hur man placerar dem där de introduceras.

Så här fungerar kartregler

Varje kartregel har fyra delar:

Fastighet	Obligatoriskt	Beskrivning
`inputs`	Ja	Lista över fältvägar som ska läsas från det inkommande meddelandet.
`output`	Ja	Fält där resultatet visas i utdatameddelandet.
`expression`	No	Formel som tillämpas på indatavärdena. Om du utelämnar det kopieras det första indatavärdet direkt.
`description`	No	Läsbar etikett för regeln, som ingår i felmeddelanden.

Mapptransformen tilldelar positionsvariabler till indata i ordning. Till exempel, om inputs är , så ['Position', 'Office'] är värdet på $1 och Position är värdet på $2Office.

Byt namn på ett fält

Om du vill byta BirthDate namn till DateOfBirthmappar du en indata till en annan utdatasökväg. Du behöver inget uttryck. Värdet kopieras oförändrat.

Lägg till en regel i konfigurationen för karttransformering:

Inställning	Värde
Input	`BirthDate`
Resultat	`DateOfBirth`

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

- inputs:
    - BirthDate
  output: DateOfBirth

Omstrukturera fält

Använd punktnotation i utdatavägen för att flytta fält till en kapslad struktur.

Lägg till två regler:

Input	Resultat
`Name`	`Employee.Name`
`BirthDate`	`Employee.DateOfBirth`

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med 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'
}

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

- inputs:
    - Name
  output: Employee.Name

- inputs:
    - BirthDate
  output: Employee.DateOfBirth

Med dessa indata:

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

Dessa två regler skapar:

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

Endast fält som anges i en regels utdata visas i resultatet. Resultatet inkluderar Position inte fältet eftersom ingen regel mappar det.

Kombinera flera indata

När du listar flera indata, använd deras positionsvariabler för att slå ihop dem i ett uttryck.

Lägga till en regel:

Inställning	Värde
Ingångar	`Position`, `Office`
Resultat	`Employment.Position`
Uttryck	`$1 + ", " + $2`

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

Givet Position: "Analyst" och Office: "Kent, WA" är resultatet "Analyst, Kent, WA".

Transformera värden med uttryck

Använd fältet expression för att tillämpa inbyggda funktioner eller aritmetik. Följande exempel använder cToF, en inbyggd enhetskonverteringsfunktion som omvandlar ett Celsiusvärde till Fahrenheit. Kom ihåg att det $1 syftar på den första inmatningen, inte på ett fältnamn.

För den fullständiga listan över operatorer, funktioner och avancerade funktioner, se referensen Expressions. Referensgrupperna grupperar funktioner efter kategori, såsom enhetskonvertering, skalning och avrundning, matematik och strängfunktioner .

Lägg till en beräkningsregel. Om du till exempel vill konvertera Celsius till Fahrenheit:

Inställning	Värde
Input	`temperature`
Resultat	`temperature_f`
Uttryck	`cToF($1)`

Om du vill skala en sensoravläsning till ett 0–100-intervall använder du uttrycket scale($1, 0, 4095, 0, 100).

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

Så här skalar du en sensoravläsning:

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

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

Så här skalar du en sensoravläsning:

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

Så här skalar du en sensoravläsning:

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

Kopiera alla fält med wildcards

När utdata noggrant ska matcha indata med bara några få ändringar använder du en jokerteckenregel för att kopiera varje fält samtidigt. Lägg sedan till regler för att åsidosätta, lägga till eller ta bort specifika fält.

Lägg till en genomströmningsregel som kopierar alla fält. Ange indata till * och utdata till *.

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

Krav för wildcard-regler

En wildcardregel måste vara den första regeln i kartkonfigurationen.
En karttransform stöder endast en wildcard-regel.
Asterisken matchar ett eller flera sökvägssegment och måste representera ett fullständigt segment. Karttransformen stöder inte partiella mönster som partial*.

Jokertecken för prefix

Begränsa jokern till ett specifikt prefix. För att platta ut alla fält från ColorProperties till rotnivå:

Lägg till en regel med indata ColorProperties.* och utdata *.

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

Givet:

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

Resultatet är:

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

Ta bort fält från utdata

output Ange till en tom sträng för att exkludera specifika fält. Brukar du använda detta tillvägagångssätt efter en jokerregel: kopiera allt och ta sedan bort det du inte behöver.

Lägg till en pass-through-regel för att kopiera alla fält.
Lägg till en borttagningsregel och välj de fält som ska undantas (till exempel password och internal_id).

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

- inputs:
    - password
    - internal_id
  output: ""

En borttagningsregel kan inte inkludera ett uttryck.

Åsidosätt wildcards för specifika fält

När en jokerteckenregel och en specifik regel båda matchar samma fält har den mer specifika regeln företräde.

Lägg till en pass-through-regel för att kopiera alla fält.
Lägg till en beräkningsregel för temperature med uttrycket cToF($1).

Karttransformningen tillämpar den specifika regeln på temperature och kopierar alla andra fält as-is.

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

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

Använda metadatafält

Läs från och skriv till meddelandemetadata som MQTT-ämnen och användaregenskaper. Se Metadatafält i uttrycksreferensen.

Lägg till en regel med indata region och utdata $metadata.user_property.region för att skriva ett fältvärde till en MQTT-användaregenskap.

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

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

Ett fullständigt exempel på dynamisk ämnesroutning finns i Dirigera meddelanden till olika ämnen.

Använd senast kända värde och standardvärden

När sensordata anländer tillfälligt kan du fylla i saknade fält med det senast kända värdet eller ett statiskt standardvärde. Se Senaste kända värde och Standardvärden i uttrycksreferensen.

Lägg till en regel för fältet temperature och aktivera Senaste kända värde. Ange ett standardvärde för 0 som reserv.

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

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

Den här regeln använder det aktuella värdet när det finns, återgår till det senast kända värdet och använder 0 om inget av dem är tillgängligt.

Berika med externa data

Berikning är frivilligt. Du behöver det bara om du vill kombinera inkommande meddelanden med referensdata som lagras i state store, till exempel en uppslagstabell över enhetens metadata. Om dina meddelanden redan innehåller allt du behöver, hoppa över denna sektion.

När du behöver berikning, konfigurera en kontextualiseringsdatamängd som körtiden söker upp under bearbetningen. Du kan till exempel slå upp en enhets metadata med dess ID och inkludera dem i utdata. Mer information finns i Berika med externa data.

Exklusiva funktioner för dataflödesdiagram

Dataflödesdiagram stöder flera funktioner som inte är tillgängliga i dataflödesmappningar builtInTransformation .

Standardvärden för saknade fält

Använd syntaxen ?? <default> för indata för att tillhandahålla en statisk återställning när ett fält saknas. Det här är enklare än att skriva ett if uttryck för att söka efter tomma värden.

I konfigurationen för karttransformering anger du att indata ska innehålla syntaxen ?? följt av standardvärdet. Ange till exempel temperature ?? 0 som indatafält som ska användas 0 när temperaturfältet saknas.

CLI tillämpar hela grafen från en konfigurationsfil, så lägg till den på motsvarande plats i din graph.json och tillämpa den med az iot ops dataflowgraph apply:

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

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

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

- inputs:
    - temperature ?? 0
  output: temperature

Mer information om standardtyper som stöds och hur du kombinerar standardvärden med senast kända värden finns i Standardvärden i uttrycksreferensen.

Regex-funktioner

Dataflödesdiagram stöder matchning och ersättning av reguljära uttryck:

str::regex_matches(string, pattern): Returnerar true om strängen matchar regex-mönstret.
str::regex_replace(string, pattern, replacement): Ersätter alla regex-matchningar med ersättningssträngen.

Dessa funktioner är användbara i filteruttryck eller för att rensa och transformera strängdata. En fullständig lista över strängfunktioner finns i Strängfunktioner i uttrycksreferensen.

Fullständigt konfigurationsexempel

Här är en fullständig mappningskonfiguration som kopierar alla fält, tar bort känsliga data, omstrukturerar ett fält och beräknar ett härlett värde:

Skärmbild av konfigurationspanelen för operationskartans erfarenhetstransformering som visar flera regler för att använda jokertecken, ta bort, omstrukturera, beräkna och sammanfoga.

I driftmiljön skapar du ett dataflödesdiagram och lägger till en karttransformering. I kartkonfigurationspanelen lägger du till regler i:

Kopiera alla fält med jokerteckengenomströmning.
Ta bort känsliga fält genom att ange att utdata ska vara tomma för password och secret_key.
Omstrukturera fältet BirthDate till Employee.DateOfBirth.
Beräkna en Fahrenheit-omvandling med hjälp av formeln cToF($1) på temperature fältet.
Sammanfoga fälten Position och Office med formeln $1 + ", " + $2.

Azure CLI använder ett dataflödesdiagram från en enda JSON-konfigurationsfil. Skapa en graph.json fil med grafegenskaperna. I graph.json filen lagrar value fältet varje transforms regler som en escaped JSON-sträng. Den läsbara formen för varje transformerings regler finns i instruktioner för den transformeringstypen.

{
  "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"
      }
    }
  ]
}

Tip

För att generera den escaped-strängen sparar du reglerna i en fil med namn som rules.json, kör jq -c . rules.json och klistrar in utdata på en enda rad i fältet value.

Använd konfigurationsfilen.

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' }
      }
    ]
  }
}

Viktigt!

Användning av Kubernetes-distributionsmanifest stöds inte i produktionsmiljöer och bör endast användas för felsökning och testning.

Regelkonfigurationen är en JSON-sträng som placeras som value för rules nyckeln i en DataflowGraph transformnods configuration sektion.

{
  "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"
    }
  ]
}

DataflowGraph Fullständig resursstruktur finns i Översikt över dataflödesdiagram.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-07-31

Transformera data med karta i dataflödesdiagram

Förutsättningar

Så här fungerar kartregler

Byt namn på ett fält

Omstrukturera fält

Kombinera flera indata

Transformera värden med uttryck

Kopiera alla fält med wildcards

Krav för wildcard-regler

Jokertecken för prefix

Ta bort fält från utdata

Åsidosätt wildcards för specifika fält

Använda metadatafält

Använd senast kända värde och standardvärden

Berika med externa data

Exklusiva funktioner för dataflödesdiagram

Standardvärden för saknade fält

Regex-funktioner

Fullständigt konfigurationsexempel

Relaterat innehåll

Feedback

Ytterligare resurser