Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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
- Istanza di Operazioni di Azure IoT distribuita in un cluster Kubernetes. Per altre informazioni, vedere Deploy Operazioni di Azure IoT.
- Un endpoint del Registro di sistema predefinito denominato
defaultche punta amcr.microsoft.comviene 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 |
Sì | Elenco dei percorsi dei campi da leggere dal messaggio in arrivo. |
output |
Sì | 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.
- Aggiungere una regola pass-through per copiare tutti i campi.
- Aggiungere una regola di rimozione e selezionare i campi da escludere , ad esempio
passwordeinternal_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.
- Aggiungere una regola pass-through per copiare tutti i campi.
- Aggiungere una regola di calcolo per
temperaturecon l'espressionecToF($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:
Nell'esperienza operativa, creare un grafico del flusso di dati e aggiungere 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
passwordesecret_key. -
Ristrutturare il
BirthDatecampo inEmployee.DateOfBirth. -
Calcolare una conversione Fahrenheit usando la formula
cToF($1)sultemperaturecampo. -
Unire il
Positione ilOfficecon la formula$1 + ", " + $2.