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

Una trasformazione mappa accetta ogni messaggio in arrivo e genera un messaggio di output basato sulle 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

  • 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

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

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

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

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

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. Questo approccio viene in genere usato dopo una regola con wildcard: copiare tutto, quindi rimuovere ciò che non è necessario.

  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.

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.

  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

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

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

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

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) nel temperature campo.
  5. Unire il Position e il Office con la formula $1 + ", " + $2.

Passaggi successivi

  • Last updated on