Informazioni di riferimento sulle espressioni per i flussi di dati

Questo riferimento si applica sia ai flussi di dati che ai grafici del flusso di dati. Entrambi usano lo stesso linguaggio delle espressioni per le trasformazioni di mapping, filtro e arricchimento. I grafici del flusso di dati supportano anche trasformazioni di rami e finestre (accumulo), indicate se applicabile.

Variabili posizionale

La matrice di inputs ogni regola determina le variabili disponibili in expression. Il primo input diventa $1, il secondo diventa $2e così via.

Se viene specificato un solo input e non viene specificata alcuna espressione, il valore in corrispondenza dell'input viene copiato direttamente nell'output.

Operatori

Le espressioni supportano gli operatori seguenti, elencati dalla precedenza più alta alla più bassa:

L'operatore + concatena le stringhe quando almeno un operando è una stringa. Usare le parentesi per eseguire l'override della precedenza predefinita.

Esempi:

Funzioni predefinite

Funzioni di conversione unità

Queste funzioni accettano un singolo valore numerico e restituiscono un valore float.

Funzioni di ridimensionamento e arrotondamento

Funzioni matematiche

Queste funzioni provengono dalla libreria matematica predefinita.

Funzioni stringa

Funzioni condizionali e di raccolta

Funzioni di aggregazione (solo trasformazioni di finestra)

Queste funzioni sono disponibili solo nelle regole di accumulo all'interno delle trasformazioni di finestra. Ognuno accetta una singola variabile posizionale.

Per informazioni dettagliate sull'uso delle funzioni di aggregazione, vedere Aggregare i dati nel tempo.

Logica condizionale

Usare la funzione per diramare la if logica all'interno di un'espressione:

Usare () (il valore vuoto) nei confronti per rilevare i campi mancanti.

Campi dei metadati

Leggere e scrivere nei metadati dei messaggi usando il $metadata. prefisso nei inputs campi o output di una regola. I riferimenti ai metadati vengono inseriti nel percorso del campo, non nell'espressione stessa.

Proprietà dei metadati

• Argomento: funziona sia per MQTT che per Kafka. Contiene la stringa in cui è stato pubblicato il messaggio. Esempio: $metadata.topic.
• Proprietà utente: in MQTT, si riferisce alle coppie chiave/valore in formato libero che un messaggio MQTT può contenere. Ad esempio, se il messaggio MQTT è stato pubblicato con una proprietà utente con la chiave "priority" e il valore "high", il $metadata.user_property.priority riferimento contiene il valore "high". Le chiavi delle proprietà utente possono essere stringhe arbitrarie e possono richiedere l'uso di caratteri di escape: $metadata.user_property."weird key" utilizza la chiave "chiave strana" (che contiene uno spazio).
• Proprietà di sistema: questo termine viene usato per ogni proprietà che non è una proprietà utente. Attualmente è supportata solo una singola proprietà di sistema: $metadata.system_property.content_type, che legge la proprietà del tipo di contenuto del messaggio MQTT (se impostata).
• Intestazione: Questa è l'equivalente Kafka della proprietà utente MQTT. Kafka può usare qualsiasi valore binario per una chiave, ma i flussi di dati supportano solo chiavi stringa UTF-8. Esempio: $metadata.header.priority. Questa funzionalità è simile alle proprietà utente.

Leggere dai metadati

Per fare riferimento all'argomento di origine e a una proprietà utente in un'espressione, elencarli come input:

Espressione: $1 + "/" + $2

Nell'esempio seguente, la proprietà MQTT topic è mappata nel campo origin_topic nell'output.

Se la proprietà priority utente è presente nel messaggio MQTT, l'esempio seguente illustra come eseguirne il mapping a un campo di output:

Scrivere nei metadati

Per impostare una proprietà utente nel messaggio di output, usare $metadata.user_property.<key> come campo di output.

L'impostazione di un campo di metadati su un valore vuoto (()) lo rimuove. Per le proprietà utente, sono consentite chiavi duplicate.

È anche possibile eseguire il mapping delle proprietà dei metadati a un'intestazione di output o a una proprietà utente. Nell'esempio seguente, il MQTT topic è mappato al campo origin_topic nella proprietà utente dell'output.

Se il payload in ingresso contiene un priority campo, l'esempio seguente illustra come eseguirne il mapping a una proprietà utente MQTT:

Lo stesso esempio per Kafka:

I campi dei metadati sono supportati nelle regole di mapping, filtro e ramo. Non sono disponibili nelle regole di finestra (accumulo).

Ultimo valore noto

Usare il ? $last suffisso su un input per indicare al runtime di ricordare il valore più recente per tale campo. Se il campo non è presente nel messaggio corrente, viene invece utilizzato l'ultimo valore noto.

La ? $last direttiva non fa distinzione tra maiuscole e minuscole e supporta spazi vuoti flessibili.

L'ultimo valore noto è supportato nelle regole di mapping, filtro e ramo. Non è disponibile nelle regole di finestra (accumulo).

Valori predefiniti

Usare il ?? <default> suffisso su un input per fornire un valore di fallback quando il campo non è presente. Tipi predefiniti supportati: integer, float, boolean, string e null.

Combinare l'ultimo valore noto e il valore predefinito

È possibile combinare ? $last e ?? <default>. Il runtime controlla prima il messaggio corrente, quindi l'ultimo valore noto, quindi il valore predefinito. Se si usa ?? <default> senza ? $last, il runtime controlla direttamente il messaggio corrente e quindi il valore predefinito.

I valori predefiniti sono supportati nelle regole di mapping, filtro e ramo. Non sono disponibili nelle regole di finestra (accumulo).

Tipi di dati

Gli oggetti JSON e le matrici vengono mantenuti as-is quando i campi vengono copiati senza un'espressione, ma non possono essere usati come input per la valutazione delle espressioni.

Supporto delle funzionalità per tipo di trasformazione

¹ Disponibile solo nei grafici del flusso di dati. Non supportato negli input del flusso builtInTransformation di dati.

Notazione e escape dei punti

La notazione punto viene ampiamente usata per fare riferimento a campi annidati. Un percorso di notazione punto standard è simile a Person.Address.Street.Number.

In un flusso di dati, un percorso descritto dalla notazione punto può includere stringhe e alcuni caratteri speciali senza dover eseguire l'escape, ad esempio Person.Date of Birth.

In altri casi, l'escape è necessario, ad esempio: nsu=http://opcfoundation.org/UA/Plc/Applications;s=RandomSignedInt32. Questo percorso, tra gli altri caratteri speciali, contiene punti all'interno del nome del campo. Senza escape, il nome del campo fungerebbe da separatore nella notazione del punto stesso.

Mentre un flusso di dati analizza un percorso, tratta solo due caratteri come speciali:

• I punti (.) fungono da separatori di campo.
• Le virgolette singole, se posizionate all'inizio o alla fine di un segmento, iniziano una sezione di escape in cui i punti non vengono considerati come separatori di campo.

Tutti gli altri caratteri vengono considerati come parte del nome del campo. Questa flessibilità è utile in formati come JSON, in cui i nomi dei campi possono essere stringhe arbitrarie.

La definizione del percorso deve inoltre rispettare le regole del formato di configurazione. Quando un carattere con un significato speciale viene incluso nel percorso, è necessario inserire le virgolette appropriate. Ad esempio, i nomi di campo che iniziano con due punti (ad :Person:.:name:esempio ) o che iniziano con un numero seguito da testo (ad 100 celsius.hotesempio ) devono essere interpretati correttamente come stringhe.

Evasione

La funzione primaria di escape in un percorso con notazione punto consiste nell'usare punti che fanno parte dei nomi dei campi anziché dei separatori. Ad esempio, il percorso Payload."Tag.10".Value è costituito da tre segmenti: Payload, Tag.10e Value. Le virgolette doppie impediscono Tag.10 al punto di fungere da separatore.

Regole di escape nella notazione con punti

• Esegui l'escape di ciascun segmento separatamente: nel caso in cui più segmenti contengano punti, tali segmenti devono essere racchiusi tra virgolette doppie. Anche altri segmenti possono essere racchiusi tra virgolette, ma non influisce sull'interpretazione del percorso. Ad esempio: Payload."Tag.10".Measurements."Vibration.$12".Value

• Uso corretto delle virgolette doppie: le virgolette doppie devono aprire e chiudere un segmento di testo tra virgolette. Tutte le virgolette al centro del segmento vengono considerate parte del nome del campo. Ad esempio, il percorso Payload.He said: "Hello", and waved definisce due campi: Payload e He said: "Hello", and waved. Quando un punto viene visualizzato in queste circostanze, continua a fungere da separatore. Ad esempio, il percorso Payload.He said: "No. It is done" viene suddiviso nei segmenti Payload, He said: "Noe It is done" (a partire da uno spazio).

Algoritmo di segmentazione

• Se il primo carattere di un segmento è una virgoletta, il parser cerca la virgoletta successiva. La stringa racchiusa tra queste virgolette è considerata un singolo segmento.
• Se il segmento non inizia con virgolette, il parser identifica i segmenti cercando il punto successivo o la fine del percorso.

Caratteri jolly

Usare un carattere jolly (*) nei percorsi di input e output per trovare una corrispondenza con più campi contemporaneamente. Ciò è utile quando l'output è simile all'input o quando è necessario applicare la stessa trasformazione in molti campi senza elencarne uno.

Copiare tutti i campi

Per passare ogni campo senza modifiche:

Corrisponde * a ogni percorso di campo nell'input e lo inserisce nello stesso percorso nell'output. La parte del percorso corrispondente * viene chiamata segmento acquisito. Nell'output il segmento acquisito sostituisce .*

Appiattire i campi annidati

Per spostare i campi da un oggetto annidato al livello radice, inserire il prefisso nell'input e * nell'output:

Dato questo input:

{
  "Sensors": { "Temperature": 72.5, "Pressure": 14.7 },
  "Metadata": { "LineId": "Line-3", "Shift": "A" }
}

L'output rende flat entrambi gli oggetti:

{
  "Temperature": 72.5,
  "Pressure": 14.7,
  "LineId": "Line-3",
  "Shift": "A"
}

Ristrutturare i campi

Per spostare i campi in un nuovo elemento padre, inserire * l'input e aggiungere un prefisso nell'output:

In questo modo vengono inclusi tutti i campi di primo livello all'interno di un Telemetry oggetto .

Regole di posizionamento con caratteri jolly

• È consentito un solo valore* per input o percorso di output.
• Deve * corrispondere a un segmento completo (non a un segmento parziale come Sensor*).
• Può * essere visualizzato all'inizio (*.Value), al centro (Sensors.*.Reading) o alla fine (Sensors.*) di un percorso.

Caratteri jolly a più input

Quando una regola ha più input con caratteri jolly, deve * acquisire lo stesso segmento in tutti gli input. Il runtime risolve l'oggetto * dal primo input, quindi cerca i percorsi corrispondenti negli altri input.

Ad esempio, per mediare le letture massime e minime per ogni sensore:

Dato questo input:

{
  "Temperature": { "Max": 85.3, "Min": 62.1 },
  "Pressure": { "Max": 15.2, "Min": 14.1 }
}

L'oggetto * acquisisce Temperature prima di tutto, quindi la regola cerca sia Temperature.Max che Temperature.Min. Acquisisce Pressure quindi e cerca Pressure.Max e Pressure.Min. L'output è il seguente:

{
  "Averaged": { "Temperature": 73.7, "Pressure": 14.65 }
}

Se un input non può essere risolto per un segmento acquisito(ad esempio, *.Mid.Avg quando il campo è annidato in modo diverso), tale segmento viene ignorato. Assicurarsi che i percorsi in tutti gli input riflettano la struttura effettiva dei dati.

Eseguire l'override di un carattere jolly per campi specifici

È possibile combinare una regola con caratteri jolly con regole specifiche. Le regole specifiche hanno la precedenza quando hanno una copertura inferiore (meno segmenti corrispondono a *). Questa operazione è denominata specializzazione.

La prima regola si applica a tutti i campi. La seconda regola esegue l'override solo per Pressure , perché Pressure.Max è più specifica di *.Max (copertura 0 e copertura 1).

Per escludere completamente un campo, usare un output vuoto:

Un output vuoto elimina il campo dal risultato. In questo modo viene eseguito l'override di qualsiasi regola con caratteri jolly che altrimenti lo includerebbe.

Più regole sugli stessi input

Se due regole hanno la stessa copertura o superiore, entrambe si applicano. In questo modo è possibile calcolare più valori derivati dagli stessi input:

Entrambe le regole vengono eseguite per ogni segmento acquisito, producendo due campi di output per sensore.

Caratteri jolly nei set di dati di contestualizzazione

È possibile usare caratteri jolly con $context riferimenti per copiare tutti i campi da un set di dati:

In questo modo ogni campo del assetMeta set di dati viene copiato nella Asset sezione dell'output.

Set di dati di contestualizzazione

I set di dati di contestualizzazione consentono ai mapping di integrare dati aggiuntivi da database esterni. Usare il $context(datasetName) prefisso per fare riferimento ai campi di un set di dati. Ad esempio, $context(position).BaseSalary legge il BaseSalary campo da un set di dati denominato position.

Per informazioni dettagliate sulla configurazione dei set di dati di contestualizzazione, vedere Arricchire i dati usando i flussi di dati e Arricchire i dati esterni nei grafici del flusso di dati.

Contenuti correlati

• Eseguire il mapping di dati usando flussi di dati
• Filtrare i dati in un flusso di dati
• Trasformare i dati con la mappa nei grafici del flusso di dati
• Filtrare e instradare i dati nei grafici del flusso di dati
• Aggregare i dati nel tempo
• Arricchire con dati esterni