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

In Operazioni di Azure IoT, una trasformazione mappa prende ogni messaggio in entrata in un grafico di flusso dati e produce un messaggio di output basato sulle tue regole. È possibile rinominare i campi, riorganizzarli in nuove strutture, calcolare i valori derivati o rimuovere campi indesiderati. Utilizzando le regole jolly, puoi 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.

Le trasformazioni utilizzano un linguaggio di espressione per calcolare valori, condizioni di test e campi di riferimento. Le espressioni si riferiscono agli input per posizione, non per nome: il primo input nella inputs lista è $1, il secondo è $2, e così via. Funzioni integrate come cToF convertono e manipolano tali valori.

Per l'elenco completo di operatori, funzioni, tipi di dati e campi di metadati, consulta il riferimento Expressions.

Prerequisiti

  • 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.

Gli esempi interfaccia della riga di comando di Azure in questo articolo usano variabili di ambiente così puoi impostare ogni valore una volta e poi copiare e incollare i comandi as-is. Se stai usando l'ambiente Operazioni di Azure IoT Codespaces dal quickstart, queste variabili sono già impostate per te e puoi saltare questo passaggio. Altrimenti, imposta le seguenti variabili di ambiente nella tua shell prima di eseguire i comandi.

I seguenti script impostano le variabili di ambiente più comunemente utilizzate:

Variabile di ambiente Descrizione
SUBSCRIPTION_ID L'ID dell'abbonamento che contiene la tua istanza Operazioni di Azure IoT.
RESOURCE_GROUP Il nome del gruppo di risorse che contiene la tua istanza Operazioni di Azure IoT.
AIO_INSTANCE_NAME Il nome della tua istanza Operazioni di Azure IoT. Per elencare le tue istanze, esegui az iot ops list -o table.
CLUSTER_NAME Il nome del cluster Kubernetes abilitato Azure Arc che ospita la tua istanza.
LOCATION La regione Azure da utilizzare per nuove risorse, ad esempio eastus.
SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

Devi solo impostare le variabili utilizzate in questo articolo. Questo articolo potrebbe utilizzare variabili ambientali aggiuntive per i nomi delle risorse che scegli. L'articolo spiega come posizionarli dove vengono introdotti.

Funzionamento delle regole della mappa

Ogni regola della mappa ha quattro parti:

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

La trasformata della mappa assegna le variabili posizionali agli input in ordine. Ad esempio, se inputs è , allora ['Position', 'Office'] è il valore di $1 e Position è il valore di $2Office.

Rinominare un campo

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

Nella configurazione della trasformazione mappa aggiungere una regola:

Impostazione Valore
Inserimento BirthDate
Risultato 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

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 risultato non include il Position campo perché nessuna regola lo mappa.

Combinare più input

Quando elenchi più input, usa le loro variabili posizionali per unirle in un'espressione.

Aggiungi una regola:

Impostazione Valore
Inputs Position, Office
Risultato 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. Il seguente esempio utilizza cToF, una funzione di conversione unitaria integrata che converte un valore Celsius in Fahrenheit. Ricorda che si $1 riferisce al primo input, non a un nome di campo.

Per l'elenco completo di operatori, funzioni e funzionalità avanzate, consulta il riferimento Expressions. Il riferimento raggruppa funzioni per categoria, come conversione di unità, scala e arrotondamento, matematica e funzioni di stringa .

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).

Copiare 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 *.

Requisiti delle regole con caratteri jolly

  • Una regola con caratteri jolly deve essere la prima regola nella configurazione della mappa.
  • Una trasformazione mappa supporta una sola regola jolly.
  • L'asterisco corrisponde a uno o più segmenti di percorso e deve rappresentare un segmento completo. La trasformazione della mappa non supporta pattern parziali come partial*.

Caratteri jolly come prefisso

Assegna il wildcard a un prefisso specifico. Per appianare tutti i campi dal ColorProperties fino al livello radice.

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

Si consideri quanto segue:

{
  "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. Di solito, si usa questo approccio dopo una regola jolly: copia tutto, poi rimuovi ciò che non ti serve.

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

Una regola di rimozione non può includere un'espressione.

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.

  1. Aggiungere una regola pass-through per copiare tutti i campi.
  2. 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'è.

Usare i campi dei metadati

Leggi e scrivi sui metadati dei messaggi come 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.

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.

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

L'arricchimento è opzionale. Ti serve solo se vuoi combinare i messaggi in arrivo con i dati di riferimento memorizzati nello state store, come una tabella di ricerca dei metadati del dispositivo. Se i tuoi messaggi contengono già tutto ciò di cui hai bisogno, salta questa sezione.

Quando hai bisogno di arricchimento, configura un dataset di contestualizzazione che il runtime cerca durante l'elaborazione. 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.

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 mappa dell'esperienza operativa che mostra diverse regole per carattere jolly, rimozione, ristrutturazione, calcolo e unione.

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

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