Trasformare i dati con la mappa nei grafici del flusso di dati

Importante

Questa pagina include istruzioni per la gestione dei componenti Azure IoT Operations usando i manifesti di distribuzione kubernetes, disponibile in ANTEPRIMA. Questa funzionalità viene fornita con diverse limitazioni e non deve essere usata per i carichi di lavoro di produzione.

Consultare i Termini supplementari di utilizzo per le anteprime di Microsoft Azure per i termini legali applicabili alle funzionalità di Azure in versione beta, anteprima o non ancora rilasciate in versione generale.

Una trasformazione mappa accetta ogni messaggio in arrivo e genera un messaggio di output basato sulle tue regole. È possibile rinominare i campi, riorganizzarli in nuove strutture, calcolare i valori derivati o rimuovere campi indesiderati. Le regole con caratteri jolly consentono di copiare tutti i campi contemporaneamente.

Per una panoramica dei grafici del flusso di dati e della composizione delle trasformazioni in una pipeline, vedere Panoramica dei grafici del flusso di dati.

Prerequisiti

Istanza di Azure IoT Operations distribuita in un cluster Kubernetes abilitato per Arc. Per altre informazioni, vedere Deploy Azure IoT Operations.
Un endpoint del Registro di sistema predefinito denominato default che punta a mcr.microsoft.com viene creato automaticamente durante la distribuzione. Le trasformazioni predefinite usano questo endpoint.

Funzionamento delle regole della mappa

Ogni regola della mappa ha quattro parti:

Proprietà	Obbligatorio	Descrizione
`inputs`	Sì	Elenco dei percorsi dei campi da leggere dal messaggio in arrivo.
`output`	Sì	Percorso del campo in cui il risultato viene scritto nel messaggio di output.
`expression`	No	Formula applicata ai valori di input. Se omesso, il primo valore di input viene copiato direttamente.
`description`	No	Etichetta leggibile dall'uomo per la regola, inclusa nei messaggi di errore.

Gli input vengono assegnate variabili posizionali in base all'ordine: il primo input è $1, il secondo è $2e così via. Usare queste variabili in expression.

Rinominare un campo

Per rinominare BirthDate in DateOfBirth, associare un input a un percorso di output diverso. Non è necessaria alcuna espressione. Il valore viene copiato come tale.

Nella configurazione della trasformazione mappa aggiungere una regola:

Impostazione	Valore
Inserimento	`BirthDate`
Risultato	`DateOfBirth`

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

- inputs:
    - BirthDate
  output: DateOfBirth

Ristrutturare i campi

Usare la notazione a punto nel percorso di output per spostare i campi in una struttura nidificata.

Aggiungere due regole:

Inserimento	Risultato
`Name`	`Employee.Name`
`BirthDate`	`Employee.DateOfBirth`

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

- inputs:
    - Name
  output: Employee.Name

- inputs:
    - BirthDate
  output: Employee.DateOfBirth

Dato questo input:

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

Queste due regole producono:

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

Nel risultato vengono visualizzati solo i campi elencati nell'output di una regola. Il campo Position non è incluso perché nessuna regola lo mappa.

Combinare più input

Quando si elencano più input, le relative variabili posizionali consentono di unirle in un'espressione.

Aggiungi una regola:

Impostazione	Valore
Inputs	`Position`, `Office`
Risultato	`Employment.Position`
Expression	`$1 + ", " + $2`

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

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

Dato Position: "Analyst" e Office: "Kent, WA", l'output è "Analyst, Kent, WA".

Trasformare i valori con espressioni

Usare il expression campo per applicare funzioni predefinite o aritmetiche.

Aggiungere una regola di calcolo. Ad esempio, per convertire Celsius in Fahrenheit:

Impostazione	Valore
Inserimento	`temperature`
Risultato	`temperature_f`
Expression	`cToF($1)`

Per ridimensionare la lettura di un sensore in un intervallo compreso tra 0 e 100, usare l'espressione scale($1, 0, 4095, 0, 100).

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

Per ridimensionare la lettura di un sensore:

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

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

Per ridimensionare la lettura di un sensore:

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

Per l'elenco completo di operatori, funzioni e funzionalità avanzate, vedere Riferimenti alle espressioni.

Copia tutti i campi con caratteri jolly

Quando l'output deve corrispondere strettamente all'input con solo alcune modifiche, usare una regola jolly per copiare ogni campo in una volta sola. Aggiungere quindi regole per eseguire l'override, aggiungere o rimuovere campi specifici.

Aggiungere una regola pass-through che copia tutti i campi. Impostare l'input su * e l'output su *.

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

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

Requisiti delle regole con caratteri jolly

Una regola con caratteri jolly deve essere la prima regola nella configurazione della mappa.
Per ogni trasformazione della mappa è consentita una sola regola con caratteri jolly.
L'asterisco corrisponde a uno o più segmenti di percorso e deve rappresentare un segmento completo. I modelli come partial* non sono supportati.

Caratteri jolly con prefisso

È possibile definire l'ambito del carattere jolly con un prefisso specifico. Per appianare tutti i campi dal ColorProperties fino al livello radice.

Aggiungere una regola con input ColorProperties.* e output *.

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

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

Dedito:

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

L'output è il seguente:

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

Rimuovere i campi dall'output

Impostare output su una stringa vuota per escludere campi specifici. Questo approccio viene in genere usato dopo una regola con wildcard: copiare tutto, quindi rimuovere ciò che non è necessario.

Aggiungere una regola pass-through per copiare tutti i campi.
Aggiungere una regola di rimozione e selezionare i campi da escludere , ad esempio password e internal_id.

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

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

- inputs:
    - password
    - internal_id
  output: ""

Nessuna espressione consentita in una regola di rimozione.

Sovrascrivere i caratteri jolly per campi specifici

Quando una regola con carattere jolly e una regola specifica corrispondono entrambe allo stesso campo, la regola più specifica ha la precedenza.

Aggiungere una regola pass-through per copiare tutti i campi.
Aggiungere una regola di calcolo per temperature con l'espressione cToF($1).

La trasformazione della mappa applica la regola specifica a temperature e copia tutti gli altri campi così com'è.

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

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

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

Usare i campi dei metadati

È possibile leggere e scrivere nei metadati dei messaggi, ad esempio argomenti MQTT e proprietà utente. Vedere Campi dei metadati nel riferimento delle espressioni.

Aggiungere una regola con input region e output $metadata.user_property.region per scrivere un valore di campo in una proprietà utente MQTT.

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

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

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

Per un esempio completo del routing di argomenti dinamici, vedere Instradare i messaggi a diversi argomenti.

Usare l'ultimo valore noto e le impostazioni predefinite

Quando i dati del sensore arrivano in modo intermittente, è possibile compilare i campi mancanti con l'ultimo valore noto o un valore predefinito statico. Vedere Last known value (Ultimo valore noto ) e Default values (Valori predefiniti ) nel riferimento alle espressioni.

Aggiungere una regola per il temperature campo e abilitare Ultimo valore noto. Impostare un valore predefinito di 0 come fallback.

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

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

Questa regola usa il valore corrente quando presente, esegue il fallback all'ultimo valore noto e usa 0 se nessuno dei due è disponibile.

Arricchire con dati esterni

È possibile aumentare i messaggi con i dati di un archivio stati esterno configurando i set di dati. Ad esempio, cercare i metadati di un dispositivo in base al relativo ID e includerlo nell'output. Per informazioni dettagliate, vedere Arricchire con dati esterni.

Funzionalità esclusive del grafico del flusso di dati

I grafici del flusso di dati supportano diverse funzionalità che non sono disponibili nei mapping dei flussi builtInTransformation di dati.

Valori predefiniti per i campi mancanti

Usare la sintassi ?? <default> su un input per fornire un fallback statico quando manca un campo. Questa operazione è più semplice rispetto alla scrittura di un'espressione if per verificare la presenza di valori vuoti.

Nella configurazione della trasformazione della mappa, impostare l'input includendo la sintassi ??, seguita dal valore predefinito. Ad esempio, immettere temperature ?? 0 come campo di input per utilizzare 0 quando manca il campo relativo alla temperatura.

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

- inputs:
    - temperature ?? 0
  output: temperature

Per informazioni dettagliate sui tipi predefiniti supportati e sulla combinazione di valori predefiniti con gli ultimi valori noti, vedere Valori predefiniti nel riferimento alle espressioni.

Funzioni regex

I grafici del flusso di dati supportano la corrispondenza e la sostituzione delle espressioni regolari:

str::regex_matches(string, pattern): restituisce true se la stringa corrisponde al criterio regex.
str::regex_replace(string, pattern, replacement): sostituisce tutte le corrispondenze regex con la stringa di sostituzione.

Queste funzioni sono utili nelle espressioni di filtro o per la pulizia e la trasformazione dei dati stringa. Per l'elenco completo delle funzioni stringa, vedere Funzioni stringa nelle informazioni di riferimento sulle espressioni.

Esempio di configurazione completa

Ecco una configurazione mappa completa che copia tutti i campi, rimuove i dati sensibili, ristruttura un campo e calcola un valore derivato:

Screenshot del pannello di configurazione della trasformazione della mappa operativa che mostra diverse regole per carattere jolly, rimuovere, ristrutturare, calcolare e unire.

Nell'esperienza Operativa, crea un grafico del flusso di dati e aggiungi una trasformazione mappa. Nel pannello di configurazione della mappa aggiungere regole a:

Copiare tutti i campi con un pass-through con caratteri jolly.
Rimuovere i campi sensibili impostando l'output su vuoto per password e secret_key.
Ristrutturare il BirthDate campo in Employee.DateOfBirth.
Calcolare una conversione Fahrenheit usando la formula cToF($1) nel temperature campo.
Unire il Position e il Office con la formula $1 + ", " + $2.

resource dataflowGraph 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflowGraphs@2025-10-01' = {
  name: 'temperature-map-example'
  parent: dataflowProfile
  properties: {
    profileRef: dataflowProfileName
    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' }
      }
    ]
  }
}

La configurazione delle regole è una stringa JSON posizionata come value per la chiave rules nella sezione DataflowGraph di un nodo di trasformazione 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"
    }
  ]
}

Per la struttura completa DataflowGraph delle risorse, vedere Panoramica dei grafici del flusso di dati.

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-27