Panoramica dei grafici del flusso di dati

I grafici del flusso di dati offrono un modo flessibile per elaborare i dati durante lo spostamento nelle operazioni di Azure IoT. Un flusso di dati standard segue una sequenza fissa di arricchimento, filtro, mappa. Un grafico del flusso di dati consente di comporre trasformazioni in qualsiasi ordine, diramazione in percorsi paralleli e di aggregare i dati nelle finestre temporali.

Un grafico del flusso di dati viene definito dalla DataflowGraph risorsa personalizzata Kubernetes. Al suo interno, è possibile collegare origini, trasformazioni e destinazioni per creare pipeline di elaborazione corrispondenti allo scenario.

Flussi di dati e grafici del flusso di dati

Le operazioni IoT di Azure offrono due modi per elaborare i dati in una pipeline:

Per i nuovi progetti che usano tipi di endpoint supportati, è consigliabile usare grafici del flusso di dati. I flussi di dati rimangono completamente supportati per tutti gli scenari e supportano l'intera gamma di tipi di endpoint.

Trasformazioni disponibili

Ogni trasformazione è un passaggio di elaborazione predefinito che viene configurato con regole e collegato ad altre trasformazioni all'interno di una risorsa DataflowGraph.

Tutte le trasformazioni condividono un linguaggio delle espressioni per operatori, funzioni e riferimenti a campi. È anche possibile arricchire i messaggi con dati esterni da un archivio stati nelle trasformazioni mappa, filtro e ramo.

Come si compongono le trasformazioni

Le trasformazioni si connettono in sequenza all'interno di una DataflowGraph risorsa: Trasformazione origine > Trasformazione A > Trasformazione B > … > Destinazione.

I rami trasformano il flusso in percorsi paralleli e le trasformazioni concat li uniscono di nuovo.

È possibile concatenare qualsiasi numero di trasformazioni in qualsiasi ordine. Una pipeline con una singola trasformazione mappa è valida quanto una che filtra, dirama, mappa ciascun percorso in modo diverso, unisce e quindi aggrega su una finestra temporale.

Funzionamento della configurazione

Ogni trasformazione in un grafico del flusso di dati fa riferimento a un artefatto predefinito estratto da un registro contenitori. Per configurare il transform, passa le regole come JSON attraverso la sezione configuration della risorsa del grafo.

Un endpoint del Registro di sistema predefinito denominato default che punta a mcr.microsoft.com viene creato automaticamente quando si distribuiscono le operazioni di Azure IoT. Le trasformazioni integrate usano questo endpoint per recuperare gli artefatti dal Registro di Contenitori Microsoft. Non è necessaria alcuna configurazione aggiuntiva del Registro di sistema.

Ecco un esempio completo che legge i dati relativi alla temperatura da un argomento MQTT, converte Celsius in Fahrenheit con una trasformazione mappa e pubblica il risultato:

resource dataflowGraph 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflowGraphs@2025-10-01' = {
  name: 'temperature-conversion'
  parent: dataflowProfile
  properties: {
    profileRef: dataflowProfileName
    mode: 'Enabled'
    nodes: [
      {
        nodeType: 'Source'
        name: 'sensors'
        sourceSettings: {
          endpointRef: 'default'
          dataSources: [ 'telemetry/temperature' ]
        }
      }
      {
        nodeType: 'Graph'
        name: 'convert'
        graphSettings: {
          registryEndpointRef: 'default'
          artifact: 'azureiotoperations/graph-dataflow-map:1.0.0'
          configuration: [
            {
              key: 'rules'
              value: '{"map":[{"inputs":["temperature"],"output":"temperature_f","expression":"cToF($1)"}]}'
            }
          ]
        }
      }
      {
        nodeType: 'Destination'
        name: 'output'
        destinationSettings: {
          endpointRef: 'default'
          dataDestination: 'telemetry/converted'
        }
      }
    ]
    nodeConnections: [
      { from: { name: 'sensors' }, to: { name: 'convert' } }
      { from: { name: 'convert' }, to: { name: 'output' } }
    ]
  }
}

apiVersion: connectivity.iotoperations.azure.com/v1
kind: DataflowGraph
metadata:
  name: temperature-conversion
  namespace: azure-iot-operations
spec:
  profileRef: default
  nodes:
    - nodeType: Source
      name: sensors
      sourceSettings:
        endpointRef: default
        dataSources:
          - telemetry/temperature

    - nodeType: Graph
      name: convert
      graphSettings:
        registryEndpointRef: default
        artifact: azureiotoperations/graph-dataflow-map:1.0.0
        configuration:
          - key: rules
            value: |
              {
                "map": [
                  {
                    "inputs": ["temperature"],
                    "output": "temperature_f",
                    "expression": "cToF($1)"
                  }
                ]
              }

    - nodeType: Destination
      name: output
      destinationSettings:
        endpointRef: default
        dataDestination: telemetry/converted

  nodeConnections:
    - from: { name: sensors }
      to: { name: convert }
    - from: { name: convert }
      to: { name: output }

La pipeline definisce tre elementi: un'origine, una trasformazione (indicata da nodeType: Graph) e una destinazione. Le connessioni descrivono il modo in cui i dati vengono trasmessi tra di essi. La trasformazione configuration passa le regole come stringa JSON sotto la rules chiave.

Negli articoli sulle procedure seguenti, gli esempi si concentrano sulle regole di trasformazione stesse. Per una guida dettagliata alla creazione di un grafico del flusso di dati, vedere Creare un grafico del flusso di dati.

Trasformazioni predefinite vs. trasformazioni WASM

I grafici del flusso di dati supportano due tipi di trasformazioni:

• Le trasformazioni predefinite sono predefinite da Microsoft (map, filter, branch, concat, window). È possibile configurarli con le regole. Nessuna codifica necessaria.
• Le trasformazioni WASM sono moduli WebAssembly personalizzati che gli sviluppatori compilano e distribuiscono. Usarli quando è necessaria la logica che le trasformazioni predefinite non coprono.

Entrambi i tipi di trasformazioni vengono eseguiti all'interno della stessa DataflowGraph risorsa e possono essere misti in una singola pipeline. Per informazioni sulla compilazione e la distribuzione di trasformazioni personalizzate, vedere Usare trasformazioni WASM nei grafici del flusso di dati.

Gestione degli errori

Quando una trasformazione rileva un errore durante l'elaborazione di un messaggio (ad esempio, un campo mancante o un'espressione non valida), il messaggio viene eliminato e viene registrato un errore. La pipeline continua l'elaborazione dei messaggi successivi.

Cause comuni degli errori di elaborazione:

• Un campo a cui si fa riferimento in una regola inputs non esiste nel messaggio.
• Un'espressione di filtro o di ramo restituisce un valore non booleano.
• Un'espressione fa riferimento a un tipo di dati incompatibile, ad esempio usando un oggetto JSON in aritmetico.
• Un archivio di stato usato per l'arricchimento non è raggiungibile.

Per monitorare gli errori di elaborazione, controllare i log del pod relativi al grafico del flusso di dati o usare i punti di accesso delle metriche. Per altre informazioni, vedere Configurare l'osservabilità e il monitoraggio.

Indicazioni sulle prestazioni

Ogni trasformazione nella pipeline comporta un sovraccarico di elaborazione. Tenere presenti queste linee guida:

• Preferisce meno trasformazioni con più regole. Se sono presenti molte regole di trasformazione che operano sulla stessa struttura, inserirle in una singola trasformazione mappa anziché creare trasformazioni separate per ogni regola.
• Usare più trasformazioni quando la logica è distinta. Le trasformazioni separate hanno senso quando i diversi passaggi di elaborazione sono fondamentalmente diversi (filtro e mapping rispetto all'aggregazione).
• Mantenere insieme le regole correlate. Una singola trasformazione mappa può gestire la ridenominazione dei campi, la ristrutturazione, i campi calcolati e le trasformazioni dei metadati contemporaneamente.

Prerequisiti

Per usare i grafici del flusso di dati, è necessario:

• Istanza di Azure IoT Operations distribuita in un cluster Kubernetes abilitato per Arc. Per altre informazioni, vedere Deploy Azure IoT Operations.
• L'endpoint predefinito del registro che punta a mcr.microsoft.com, creato automaticamente durante la distribuzione.

Passaggi successivi

• Flussi di dati e grafici del flusso di dati
• Creare un grafo del flusso di dati
• Trasformare i dati con mappa
• Filtrare e instradare i dati
• Aggregare i dati nel tempo
• Arricchire con dati esterni
• Informazioni di riferimento sulle espressioni
• Indirizzare i messaggi a diversi argomenti
• Informazioni di riferimento sulle espressioni
• Usare trasformazioni WASM nei grafici del flusso di dati