Configurare le definizioni dei grafici WebAssembly (WASM) per grafici e connettori del flusso di dati

Le definizioni dei gragrafi sono fondamentali per lo sviluppo WASM perché definiscono il modo in cui i moduli si connettono ai flussi di dati e ai connettori. La comprensione della relazione tra definizioni di grafo e grafici o connettori del flusso di dati consente di sviluppare in modo efficace.

Prerequisiti

• Familiarità con lo sviluppo di moduli WASM personalizzati
• Conoscenza di base della sintassi YAML

Questo articolo è incentrato sulla creazione e la configurazione delle definizioni del grafico YAML. Per informazioni sulla distribuzione e il test dei grafici dei flussi di dati, vedere Distribuire moduli WebAssembly (WASM) e definizioni di grafo.

Struttura della definizione del grafo

Le definizioni del grafo seguono uno schema JSON formale che convalida la struttura YAML del grafo e garantisce la compatibilità. La configurazione include:

• Requisiti dei moduli per la compatibilità delle versioni API e della libreria host
• Configurazioni dei moduli per i parametri di runtime e personalizzazione dell’operatore
• Operazioni che definiscono i nodi di elaborazione nel flusso di lavoro
• Connessioni che specificano il routing del flusso di dati tra operazioni

Struttura del grafo di base

metadata:
  $schema: "https://www.schemastore.org/aio-wasm-graph-config-1.0.0.json"
  name: "Simple graph"
  description: "A simple graph with a source, a map module, and a sink"
  version: "1.0.0"
  vendor: "Microsoft"

moduleRequirements:
  apiVersion: "1.1.0"
  runtimeVersion: "1.1.0"

operations:
  - operationType: "source"
    name: "data-source"
  - operationType: "map"
    name: "my-operator/map"
    module: "my-operator:1.0.0"
  - operationType: "sink"
    name: "data-sink"

connections:
  - from: { name: "data-source" }
    to: { name: "my-operator/map" }
  - from: { name: "my-operator/map" }
    to: { name: "data-sink" }

Compatibilità delle versioni

La moduleRequirements sezione garantisce la compatibilità usando il controllo delle versioni semantiche:

moduleRequirements:
  apiVersion: "1.1.0"          # WASI API version for interface compatibility
  runtimeVersion: "1.1.0"     # Runtime version providing runtime support
  features:                    # Optional features required by modules
    - name: "wasi-nn"

Esempio 1: definizione di grafico semplice

La definizione del grafo simple illustra una pipeline di base a tre fasi che converte i dati relativi alla temperatura da Fahrenheit a Celsius:

metadata:
  name: "Simple graph"
  description: "A graph that transforms temperature from Fahrenheit to Celsius"
  version: "1.0.0"
  $schema: "https://www.schemastore.org/aio-wasm-graph-config-1.0.0.json"
  vendor: "Microsoft"

moduleRequirements:
  apiVersion: "1.1.0"
  runtimeVersion: "1.1.0"

moduleConfigurations:
  - name: module-temperature/map
    parameters:
      key1:
        name: key2
        description: key2
operations:
  - operationType: "source"
    name: "source"

  - operationType: "map"
    name: "module-temperature/map"
    module: "temperature:1.0.0"

  - operationType: "sink"
    name: "sink"

connections:
  - from:
      name: "source"
    to:
      name: "module-temperature/map"

  - from:
      name: "module-temperature/map"
    to:
      name: "sink"

Per istruzioni dettagliate sulla distribuzione, vedere Distribuire moduli WebAssembly (WASM) e definizioni di grafo. Per provare un flusso di dati che usa questo esempio, vedere Esempio 1: Distribuzione di base con un modulo WASM.

Funzionamento del grafico semplice

Questo grafico crea una pipeline di elaborazione dati semplice:

1. Operazione di origine: riceve i dati sulla temperatura dall'endpoint di origine del flusso di dati
2. Operazione di mapping: elabora i dati con il modulo TEMPERATURE WASM (temperature:1.0.0)
3. Operazione sink: invia i dati convertiti all'endpoint di destinazione del flusso di dati

Il modulo temperature converte Fahrenheit in Celsius usando la formula standard (F - 32) × 5/9 = C.

Formato di input:

{"temperature": {"value": 100.0, "unit": "F"}}

Formato di output:

{"temperature": {"value": 37.8, "unit": "C"}}

Esempio 2: definizione di grafico complesso

La definizione del grafo complex illustra un sofisticato flusso di lavoro di elaborazione di più sensori che gestisce i dati relativi a temperatura, umidità e immagine con analisi avanzate:

metadata:
  name: "Complex graph"
  description: "A graph that processes temperature and humidity data from sensors, along with snapshot data. The graph performs filtering, accumulation, and enrichment operations before sending the processed data to the sink."
  version: "1.0.0"
  $schema: "https://www.schemastore.org/aio-wasm-graph-config-1.0.0.json"
  vendor: "Microsoft"

moduleRequirements:
  apiVersion: "1.1.0"
  runtimeVersion: "1.1.0"

moduleConfigurations:
  - name: module-temperature/map
    parameters:
      key1:
        name: key2
        description: key2
  - name: module-snapshot/branch
    parameters:
      snapshot_topic:
        name: snapshot_topic
        description: Transform app snapshot_topic in snapshot branch's init routine
  - name: module-temperature/filter
    parameters:
      temperature_lower_bound:
        name: temperature_lower_bound
        description: "Minimum valid temperature in Celsius (default: -40)"
      temperature_upper_bound:
        name: temperature_upper_bound
        description: "Maximum valid temperature in Celsius (default: 3422)"
operations:
  - operationType: "source"
    name: "source"

  - operationType: delay
    name: module-window/delay
    module: window:1.0.0
  - operationType: "map"
    name: "module-format/map"
    module: "format:1.0.0"
  - operationType: map
    name: module-snapshot/map
    module: snapshot:1.0.0
  - operationType: branch
    name: module-snapshot/branch
    module: snapshot:1.0.0
  - operationType: accumulate
    name: module-snapshot/accumulate
    module: snapshot:1.0.0
  - operationType: map
    name: module-temperature/map
    module: temperature:1.0.0
  - operationType: branch
    name: module-temperature/branch
    module: temperature:1.0.0
  - operationType: filter
    name: module-temperature/filter
    module: temperature:1.0.0
  - operationType: accumulate
    name: module-temperature/accumulate
    module: temperature:1.0.0
  - operationType: accumulate
    name: module-humidity/accumulate
    module: humidity:1.0.0
  - operationType: concatenate
    name: concatenate1
    module:
  - operationType: accumulate
    name: module-collection/accumulate
    module: collection:1.0.0
  - operationType: map
    name: module-enrichment/map
    module: enrichment:1.0.0

  - operationType: "sink"
    name: "sink"

connections:
  - from:
      name: source
    to:
      name: module-window/delay

  - from:
      name: module-window/delay
    to:
      name: module-snapshot/branch

  - from:
      name: module-snapshot/branch
      arm: "False"
    to:
      name: module-temperature/branch

  - from:
      name: module-snapshot/branch
      arm: "True"
    to:
      name: module-format/map

  - from:
      name: module-format/map
    to:
      name: module-snapshot/map

  - from:
      name: module-snapshot/map
    to:
      name: module-snapshot/accumulate

  - from:
      name: module-snapshot/accumulate
    to:
      name: concatenate1

  - from:
      name: module-temperature/branch
      arm: "True"
    to:
      name: module-temperature/map

  - from:
      name: module-temperature/branch
      arm: "False"
    to:
      name: module-humidity/accumulate

  - from:
      name: module-humidity/accumulate
    to:
      name: concatenate1

  - from:
      name: module-temperature/map
    to:
      name: module-temperature/filter

  - from:
      name: module-temperature/filter
    to:
      name: module-temperature/accumulate

  - from:
      name: module-temperature/accumulate
    to:
      name: concatenate1

  - from:
      name: concatenate1
    to:
      name: module-collection/accumulate

  - from:
      name: module-collection/accumulate
    to:
      name: module-enrichment/map

  - from:
      name: module-enrichment/map
    to:
      name: sink

Per istruzioni dettagliate sulla distribuzione, vedere Distribuire moduli WebAssembly (WASM) e definizioni di grafo. Per provare un flusso di dati che usa questo esempio, vedere Esempio 2: Distribuire un grafico complesso.

Funzionamento del grafico complesso

Il grafico complesso elabora tre flussi di dati e li combina nell'analisi dei sensori arricchita:

Come illustrato nel diagramma, i dati vengono trasmessi da una singola origine attraverso più fasi di elaborazione:

1. Modulo finestra: ritarda i dati in ingresso per l'elaborazione basata sul tempo
2. Operazione ramo: instrada i dati in base al tipo di contenuto (dati del sensore e snapshot)
3. Percorso di elaborazione della temperatura:
   • Converte Fahrenheit in Celsius
   • Filtra letture non valide
   • Calcola i riepiloghi statistici nelle finestre temporali
4. Percorso di elaborazione dell'umidità:
   • Raccoglie le misurazioni dell'umidità con l'analisi statistica
5. Percorso di elaborazione delle immagini:
   • Formatta i dati delle immagini per l'elaborazione
   • Esegue il rilevamento oggetti sugli snapshot della fotocamera
6. Aggregazione finale:
   • Concatena tutti i flussi di dati elaborati
   • Aggrega i risultati multi-sensore
   • Aggiunge metadati e avvisi di sovra-temperatura

Il grafico usa moduli specializzati degli esempi Rust:

• Modulo finestra per ritardi di elaborazione basati sul tempo
• Moduli di temperatura per la conversione, il filtro e l'analisi statistica
• Modulo di umidità per l'elaborazione dei dati ambientali
• Moduli snapshot per il routing dei dati immagine e il rilevamento degli oggetti
• Modulo di formato per la preparazione dell'immagine per l'elaborazione
• Modulo di raccolta per l'aggregazione dei dati multi-sensore
• Modulo di arricchimento per l'aggiunta dei metadati e la generazione degli avvisi

Le operazioni ramo consentono l'elaborazione parallela di input di sensori diversi, consentendo al grafico di gestire in modo efficiente più tipi di dati all'interno di un singolo flusso di lavoro.

Come le definizioni dei gragrafi diventano flussi di dati

Ecco come sono correlate le definizioni dei grafici e i grafici del flusso di dati di Azure IoT Operations:

Il file YAML definisce la logica di elaborazione interna con operazioni di origine/sink definite come endpoint astratti. Questo diventa l'artefatto della definizione del grafico. I moduli a cui si fa riferimento implementano gli operatori di elaborazione effettivi come i moduli WASM. Sia le definizioni dei grafici che i moduli WASM vengono caricati in un registro contenitori (ad esempio Azure Container Registry) come artefatti OCI per l'archiviazione nel registro.

La risorsa Azure Resource Manager o Kubernetes effettua il "wrapping" della definizione del grafo e la connette agli endpoint reali come risorsa del grafico di flusso di dati. Durante la distribuzione in fase di esecuzione, il motore del flusso di dati esegue il pull degli artefatti dal Registro di sistema e li distribuisce. Per il mapping degli endpoint, le operazioni astratte di origine/sink nel grafico si connettono agli argomenti MQTT effettivi, ad Hub eventi di Azure o ad altre origini dati.

Ad esempio, questo diagramma illustra la relazione tra definizioni di grafo, moduli WASM e grafici del flusso di dati:

Per altre informazioni su come configurare i grafici del flusso di dati, vedere Usare WebAssembly con grafici del flusso di dati.

Distribuzione del Registro di sistema

Sia le definizioni dei grafici che i moduli WASM devono essere caricati in un registro contenitori come artefatti OCI (Open Container Initiative) prima che i grafici del flusso di dati possano farvi riferimento:

• Le definizioni del grafico vengono incluse in un pacchetto come artefatti OCI con tipo di supporto application/vnd.oci.image.config.v1+json
• I moduli WASM vengono inseriti come artefatti OCI contenenti il file binario WebAssembly compilato
• Usare versionamento semantico (ad esempio my-graph:1.0.0, temperature-converter:2.1.0) per la gestione corretta delle dipendenze
• Il supporto del Registro di sistema è compatibile con Azure Container Registry, Docker Hub e altri registri conformi a OCI

La separazione abilita la logica riutilizzabile in cui la stessa definizione del grafo viene distribuita con endpoint diversi. Offre l'indipendenza dell'ambiente in cui sviluppo, gestione temporanea e produzione usano origini dati diverse. Supporta anche la distribuzione modulare in cui si aggiornano le configurazioni degli endpoint senza modificare la logica di elaborazione.

Per istruzioni dettagliate sul caricamento di definizioni di grafo e moduli WASM nei registri, vedere Distribuire moduli WebAssembly (WASM) e definizioni di grafo.

Parametri di configurazione del modulo

Le definizioni dei grafici possono specificare i parametri di esecuzione per operatori WASM tramite configurazioni del modulo. Questi parametri vengono passati alla funzione init dell'operatore durante l'esecuzione, consentendo la configurazione dinamica senza ricompilare i moduli.

L'esempio seguente illustra le configurazioni dei moduli per l'esempio temperature usato nel grafico complesso:

moduleConfigurations:
  - name: module-temperature/map
    parameters:
      key1:
        name: key1
        description: "Example parameter passed to the map operator's init function"
  - name: module-temperature/filter
    parameters:
      temperature_lower_bound:
        name: temperature_lower_bound
        description: "Minimum valid temperature in Celsius (default: -40)"
      temperature_upper_bound:
        name: temperature_upper_bound
        description: "Maximum valid temperature in Celsius (default: 3422)"

Il campo name in ciascuna configurazione deve corrispondere al nome dell'operatore definito nella sezione operations del grafo. Ogni parametro in parameters diventa una tupla chiave-valore nell'elenco configuration.properties ricevuto come input dalla funzione init dell'operatore.

Per esempi dettagliati su come accedere e usare questi parametri nel codice Rust e Python, vedere parametri di configurazione Module.

Per un esempio di implementazione completo, vedere il modulo branch, che illustra l'utilizzo dei parametri per la logica di routing condizionale.

Passaggi successivi

• Sviluppare moduli WebAssembly per grafici del flusso di dati
• Usare WebAssembly con grafici del flusso di dati
• Configurare gli endpoint del Registro di sistema- Esempi di grafici del flusso di dati con convalida dello schema e composizione WIT in GitHub