Eine Kartentransformation übernimmt jede eingehende Nachricht und erzeugt eine Ausgabenachricht basierend auf Ihren Regeln. Sie können Felder umbenennen, in neue Strukturen neu organisieren, abgeleitete Werte berechnen oder unerwünschte Felder entfernen. Mithilfe von Wildcardregeln können Sie alle Felder gleichzeitig kopieren.
Eine Übersicht über Datenflussdiagramme und die Art und Weise, wie Transformationen in einer Pipeline erstellt werden, finden Sie in der Übersicht über Datenflussdiagramme.
Voraussetzungen
- Eine Instanz von Azure IoT Einsatz, die in einem Kubernetes-Cluster bereitgestellt wird. Weitere Informationen finden Sie unter Deploy Azure IoT Einsatz.
- Ein Standardregistrierungsendpunkt mit dem Namen
default , auf den mcr.microsoft.com verweist, wird während der Bereitstellung automatisch erstellt. Die integrierten Transformationen verwenden diesen Endpunkt.
Funktionsweise von Kartenregeln
Jede Kartenregel weist vier Teile auf:
| Eigentum |
Erforderlich |
Beschreibung |
inputs |
Ja |
Liste der Feldpfade, die aus der eingehenden Nachricht gelesen werden sollen. |
output |
Ja |
Feldpfad, in dem das Ergebnis in der Ausgabemeldung geschrieben wird. |
expression |
No |
Formel, die auf die Eingabewerte angewendet wurde. Wenn dieser Wert nicht angegeben wird, wird der erste Eingabewert direkt kopiert. |
description |
No |
Lesbare Bezeichnung für die Regel, die in Fehlermeldungen enthalten ist. |
Eingaben werden Positionsvariablen basierend auf ihrer Reihenfolge zugewiesen: Die erste Eingabe lautet $1, die zweite ist $2usw. Verwenden Sie diese Variablen in der expression.
Umbenennen eines Felds
Weisen Sie eine Eingabe einem anderen Ausgabepfad zu, um BirthDate in DateOfBirth umzubenennen. Es ist kein Ausdruck erforderlich. Der Wert wird unverändert kopiert.
Fügen Sie in der Kartentransformationskonfiguration eine Regel hinzu:
| Setting |
Wert |
|
Eingabe |
BirthDate |
|
Output |
DateOfBirth |
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"BirthDate"
],
"output": "DateOfBirth"
}
{
inputs: [
'BirthDate'
]
output: 'DateOfBirth'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- BirthDate
output: DateOfBirth
Neustrukturieren von Feldern
Verwenden Sie die Punktnotation im Ausgabepfad, um Felder in eine geschachtelte Struktur zu verschieben.
Fügen Sie zwei Regeln hinzu:
| Eingabe |
Output |
Name |
Employee.Name |
BirthDate |
Employee.DateOfBirth |
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit 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'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- Name
output: Employee.Name
- inputs:
- BirthDate
output: Employee.DateOfBirth
Aufgrund dieser Eingabe:
{
"Name": "Grace Owens",
"BirthDate": "19840202",
"Position": "Analyst"
}
Diese beiden Regeln erzeugen:
{
"Employee": {
"Name": "Grace Owens",
"DateOfBirth": "19840202"
}
}
Nur felder, die in der Ausgabe einer Regel aufgelistet sind, werden im Ergebnis angezeigt. Das Position-Feld ist nicht enthalten, weil es keine Regel abbildet.
Wenn Sie mehrere Eingaben auflisten, können sie mit ihren Positionsvariablen in einem Ausdruck zusammengeführt werden.
Fügen Sie eine Regel hinzu:
| Setting |
Wert |
|
Eingaben |
Position, Office |
|
Output |
Employment.Position |
|
Ausdruck |
$1 + ", " + $2 |
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"Position",
"Office"
],
"output": "Employment.Position",
"expression": "$1 + \", \" + $2"
}
{
inputs: [ 'Position', 'Office' ]
output: 'Employment.Position'
expression: '$1 + ", " + $2'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- Position # $1
- Office # $2
output: Employment.Position
expression: "$1 + \", \" + $2"
Gegeben sind Position: "Analyst" und Office: "Kent, WA", ergibt die Ausgabe "Analyst, Kent, WA".
Verwenden Sie das expression Feld, um integrierte Funktionen oder Arithmetik anzuwenden.
Fügen Sie eine Berechnungsregel hinzu. Beispiel: Um Celsius in Fahrenheit umzuwandeln:
| Setting |
Wert |
|
Eingabe |
temperature |
|
Output |
temperature_f |
|
Ausdruck |
cToF($1) |
Verwenden Sie den Ausdruck scale($1, 0, 4095, 0, 100), um einen Sensorwert auf einen Bereich von 0 bis 100 zu skalieren.
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"temperature"
],
"output": "temperature_f",
"expression": "cToF($1)"
}
So skalieren Sie einen Sensorwert:
{
"inputs": [
"raw_pressure"
],
"output": "pressure_pct",
"expression": "scale($1, 0, 4095, 0, 100)"
}
{
inputs: [ 'temperature' ]
output: 'temperature_f'
expression: 'cToF($1)'
}
So skalieren Sie einen Sensorwert:
{
inputs: [ 'raw_pressure' ]
output: 'pressure_pct'
expression: 'scale($1, 0, 4095, 0, 100)'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- temperature # $1
output: temperature_f
expression: "cToF($1)"
So skalieren Sie einen Sensorwert:
- inputs:
- raw_pressure # $1
output: pressure_pct
expression: "scale($1, 0, 4095, 0, 100)"
Die vollständige Liste der Operatoren, Funktionen und erweiterten Features finden Sie in der Referenz zu Ausdrücken.
Alle Felder mit Platzhaltern kopieren
Wenn die Ausgabe mit nur wenigen Änderungen eng mit der Eingabe übereinstimmen soll, verwenden Sie eine Platzhalterregel, um jedes Feld gleichzeitig zu kopieren. Fügen Sie dann Regeln hinzu, um bestimmte Felder außer Kraft zu setzen, hinzuzufügen oder zu entfernen.
Fügen Sie eine Passthroughregel hinzu, die alle Felder kopiert. Legen Sie die Eingabe auf * und die Ausgabe auf *.
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"*"
],
"output": "*"
}
{
inputs: [ '*' ]
output: '*'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- '*'
output: '*'
Anforderungen für Wildcardregel
- Eine Wildcardregel muss die erste Regel in Ihrer Kartenkonfiguration sein.
- Pro Zuordnungstransformation ist nur eine Wildcardregel zulässig.
- Das Sternchen entspricht einem oder mehreren Pfadsegmenten und muss ein vollständiges Segment darstellen. Muster wie
partial* werden nicht unterstützt.
Präfix-Wildcards
Sie können das Wildcard auf ein bestimmtes Präfix beschränken. Um alle Felder von ColorProperties auf die Stammbene zu flatten:
Fügen Sie eine Regel mit Eingabe ColorProperties.* und Ausgabe *hinzu.
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"ColorProperties.*"
],
"output": "*"
}
{
inputs: [ 'ColorProperties.*' ]
output: '*'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- 'ColorProperties.*'
output: '*'
Gegeben:
{
"ColorProperties": {
"Hue": "blue",
"Saturation": "90%",
"Brightness": "50%"
}
}
Die Ausgabe lautet wie folgt:
{
"Hue": "blue",
"Saturation": "90%",
"Brightness": "50%"
}
Entfernen von Feldern aus der Ausgabe
Legen Sie die output Zeichenfolge auf eine leere Zeichenfolge fest, um bestimmte Felder auszuschließen. Dieser Ansatz wird in der Regel nach einer Wildcardregel verwendet: Kopieren Sie alles, und entfernen Sie dann das, was Sie nicht benötigen.
- Fügen Sie eine Passthroughregel hinzu, um alle Felder zu kopieren.
- Fügen Sie eine Regel zum Entfernen hinzu, und wählen Sie die auszuschließenden Felder aus (z. B
password . und internal_id).
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"*"
],
"output": "*"
},
{
"inputs": [
"password",
"internal_id"
],
"output": ""
}
{
inputs: [ '*' ]
output: '*'
}
{
inputs: [ 'password', 'internal_id' ]
output: ''
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- '*'
output: '*'
- inputs:
- password
- internal_id
output: ""
Bei einer Entfernungsregel ist kein Ausdruck erlaubt.
Überschreiben von Wildcards für bestimmte Felder
Wenn eine Platzhalterregel und eine bestimmte Regel beide mit demselben Feld übereinstimmen, hat die spezifischere Regel Vorrang.
- Fügen Sie eine Passthroughregel hinzu, um alle Felder zu kopieren.
- Fügen Sie eine Berechnungsregel für
temperature mit dem Ausdruck cToF($1) hinzu.
Die Kartenumwandlung wendet die spezifische Regel auf temperature an, und kopiert alle anderen Felder unverändert.
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"*"
],
"output": "*"
},
{
"inputs": [
"temperature"
],
"output": "temperature",
"expression": "cToF($1)"
}
{
inputs: [ '*' ]
output: '*'
}
{
inputs: [ 'temperature' ]
output: 'temperature'
expression: 'cToF($1)'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- '*'
output: '*'
- inputs:
- temperature # $1
output: temperature
expression: "cToF($1)"
Sie können Lese- und Schreibvorgänge in Nachrichtenmetadaten wie MQTT-Themen und Benutzereigenschaften durchführen. Siehe Metadatenfelder in der Ausdrucksreferenz.
Fügen Sie eine Regel mit Eingabe region und Ausgabe $metadata.user_property.region hinzu, um einen Feldwert in eine MQTT-Benutzereigenschaft zu schreiben.
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"*"
],
"output": "*"
},
{
"inputs": [
"region"
],
"output": "$metadata.user_property.region"
}
{
inputs: [ '*' ]
output: '*'
}
{
inputs: [ 'region' ]
output: '$metadata.user_property.region'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- '*'
output: '*'
- inputs:
- region
output: $metadata.user_property.region
Ein vollständiges Beispiel für das dynamische Themenrouting finden Sie unter Weiterleiten von Nachrichten zu verschiedenen Themen.
Zuletzt bekannte Werte und Standardwerte verwenden
Wenn Sensordaten zeitweise eintreffen, können Sie fehlende Felder mit dem letzten bekannten Wert oder einem statischen Standardwert ausfüllen. Siehe zuletzt bekannte Werte und Standardwerte in der Ausdrucksreferenz.
Fügen Sie eine Regel für das temperature Feld hinzu, und aktivieren Sie den zuletzt bekannten Wert. Legen Sie einen Standardwert 0 als Fallback fest.
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"temperature ? $last ?? 0"
],
"output": "temperature"
}
{
inputs: [ 'temperature ? $last ?? 0' ]
output: 'temperature'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- temperature ? $last ?? 0 # $1
output: temperature
Diese Regel verwendet den aktuellen Wert, wenn dieser vorhanden ist, und fällt auf den letzten bekannten Wert zurück. Falls keiner dieser Werte verfügbar ist, wird 0 verwendet.
Anreichern mit externen Daten
Sie können Nachrichten mit Daten aus einem externen Zustandsspeicher erweitern, indem Sie Datasets konfigurieren. Suchen Sie beispielsweise nach den Metadaten eines Geräts anhand der ID, und fügen Sie sie in die Ausgabe ein. Ausführliche Informationen finden Sie unter "Anreichern mit externen Daten".
Exklusive Funktionen des Datenflussdiagramms
Datenflussdiagramme unterstützen mehrere Features, die in Datenflusszuordnungen builtInTransformation nicht verfügbar sind.
Standardwerte für fehlende Felder
Verwenden Sie die ?? <default> Syntax für eine Eingabe, um einen statischen Fallback bereitzustellen, wenn ein Feld fehlt. Dies ist einfacher als das Schreiben eines if Ausdrucks zum Überprüfen auf leere Werte.
In der Konfiguration der Kartentransformation muss die Eingabe so eingestellt werden, dass sie die Syntax ?? gefolgt vom Standardwert enthält. Geben Sie zum Beispiel temperature ?? 0 als Eingabefeld ein, um 0 zu verwenden, wenn das Temperaturfeld fehlt.
Die CLI wendet das gesamte Diagramm aus einer Konfigurationsdatei an, fügen Sie dies also an die entsprechende Stelle in Ihrem graph.json hinzu, und wenden Sie es mit az iot ops dataflowgraph apply:
{
"inputs": [
"temperature ?? 0"
],
"output": "temperature"
}
{
inputs: [ 'temperature ?? 0' ]
output: 'temperature'
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
- inputs:
- temperature ?? 0
output: temperature
Ausführliche Informationen zu unterstützten Standardtypen und das Kombinieren von Standardwerten mit zuletzt bekannten Werten finden Sie unter Standardwerte in der Ausdrucksreferenz.
Regex-Funktionen
Datenflussdiagramme unterstützen das Übereinstimmen und Ersetzen regulärer Ausdrücke.
-
str::regex_matches(string, pattern): Gibt true zurück, wenn die Zeichenfolge mit dem regex-Muster übereinstimmt.
-
str::regex_replace(string, pattern, replacement): Ersetzt alle regex-Übereinstimmungen durch die Ersetzungszeichenfolge.
Diese Funktionen sind nützlich bei Filterausdrücken oder zum Bereinigen und Transformieren von Zeichenfolgendaten. Eine vollständige Liste der Zeichenfolgenfunktionen finden Sie in der Ausdrucksreferenz unter " Zeichenfolgenfunktionen ".
Vollständiges Konfigurationsbeispiel
Hier ist eine vollständige Kartenkonfiguration, die alle Felder kopiert, vertrauliche Daten entfernt, ein Feld neu strukturiert und einen abgeleiteten Wert berechnet:
Erstellen Sie in der Betriebsumgebung ein Datenflussdiagramm, und fügen Sie eine Kartentransformation hinzu. Fügen Sie im Kartenkonfigurationsbereich Regeln hinzu:
-
Kopieren Sie alle Felder mit einer Wildcard-Passthrough.
-
Entfernen Sie vertrauliche Felder, indem Sie die Ausgabe für
password und secret_key auf leer setzen.
-
Strukturieren Sie das
BirthDate Feld in Employee.DateOfBirth.
-
Berechnen Sie eine Fahrenheit-Konvertierung mithilfe der Formel
cToF($1) im temperature Feld.
-
Zusammenführen der Felder
Position und Office mit der Formel $1 + ", " + $2.
Die Azure CLI wendet ein Datenflussdiagramm aus einer einzelnen JSON-Konfigurationsdatei an. Erstellen Sie eine graph.json Datei mit den Diagrammeigenschaften. In der graph.json Datei werden die Regeln jeder Transformation im value Feld als ESCAPE-JSON-Zeichenfolge gespeichert. Informationen zur lesbaren Form der Regeln der einzelnen Transformationen finden Sie in der Vorgehensweise für diesen Transformationstyp.
{
"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
Um die escaped-Zeichenfolge zu generieren, speichern Sie die Regeln in einer Datei wie rules.json,, führen jq -c . rules.json Sie dann die einzeilige Ausgabe aus, und fügen Sie sie in das value Feld ein.
Wenden Sie die Konfigurationsdatei an. Die extendedLocation Datei wird automatisch aus der Instanz und Ressourcengruppe hinzugefügt. Fügen Sie sie daher nicht in die Datei ein.
az iot ops dataflowgraph apply \
--name temperature-map-example \
--instance <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' }
}
]
}
}
Von Bedeutung
Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.
Die Regelkonfiguration ist eine JSON-Zeichenfolge, die als value für den rules Schlüssel im DataflowGraph Abschnitt eines configuration Transformationsknotens platziert wird:
{
"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"
}
]
}
Die vollständige DataflowGraph Ressourcenstruktur finden Sie in der Übersicht über Datenflussdiagramme.
Nächste Schritte