Wyrażenia referencyjne dla przepływów danych i grafów przepływu danych

Ta dokumentacja dotyczy zarówno przepływów danych , jak i wykresów przepływu danych. Oba używają tego samego języka wyrażeń do przekształcania map, filtrowania i wzbogacania. Wykresy przepływu danych obsługują również przekształcenia gałęzi i okien (skumulowanych), które są zanotowane tam, gdzie ma to zastosowanie.

Zmienne pozycyjne

Tablica inputs każdej reguły określa zmienne dostępne w obiekcie expression. Pierwsze dane wejściowe stają się $1wartością , a druga staje się $2i tak dalej.

Jeśli określono tylko jedno dane wejściowe i nie podano żadnego wyrażenia, wartość w tym wejściu jest kopiowana bezpośrednio do danych wyjściowych.

Operatorów

Wyrażenia obsługują następujące operatory wymienione od najwyższego do najniższego pierwszeństwa:

Operator + łączy ciągi, gdy co najmniej jeden operand jest ciągiem. Użyj nawiasów, aby zastąpić domyślny pierwszeństwo.

Przykłady:

Wbudowane funkcje

Funkcje konwersji jednostek

Te funkcje akceptują pojedynczą wartość liczbową i zwracają zmiennoprzecinkowy.

Funkcje skalowania i zaokrąglania

Funkcje matematyczne

Te funkcje pochodzą z wbudowanej biblioteki matematycznej.

Funkcje łańcuchów znakowych

Funkcje daty i godziny

Funkcje daty i czasu są dostępne tylko w grafach przepływu danych. Z wyjątkiem parse_timestamp, funkcje akceptujące znacznik czasu wymagają ciągu RFC 3339 . Ciąg musi zawierać jawne przesunięcie względem Skoordynowanego Czasu Uniwersalnego (UTC), takie jak 2026-06-17T12:00:00Z lub 2026-06-17T12:00:00-08:00. Kolumna Returns zawiera typ wyniku, który typeof podaje się małymi literami jako "float", "int", lub "string".

now() odczytuje zegar systemowy węzła Kubernetes, który jest hostem obciążenia przepływu danych, za każdym razem, gdy funkcja się uruchamia. Wywołania w tym samym wyrażeniu mogą zwracać różne wartości. W zasadzie akumulacji zwraca now() się czas przetwarzania okna, a nie moment nadejścia wiadomości wejściowej. Aby zmniejszyć przesunięcie zegara między węzłami klastra, zsynchronizuj każdy zegar z wiarygodnym źródłem czasu, takim jak serwer Network Time Protocol.

Funkcje kalendarza i zegara, takie jak day_of_week, hour_of_day, oraz year_of, wykorzystują przesunięcie w znaczniku czasu wejścia. Nie przeliczają najpierw wartości na UTC. Poniższe przykłady pokazują takie zachowanie.

Format i parsowanie znaczników czasu

Funkcje format_timestamp i wykorzystują parse_timestampstrftime wzorce. Poniższa tabela przedstawia wspólne specyfikatory.

Wszystkie obsługiwane specyfikatory można znaleźć w dokumentacji Chrono strftime.

format_timestamp zachowuje przesunięcie czasu wejściowego znacznika. Na przykład format_timestamp("2026-06-09T14:00:00+02:00", "%Y-%m-%d %H:%M %:z") zwraca wartość "2026-06-09 14:00 +02:00".

parse_timestamp obsługuje wejścia w następującej kolejności:

1. Data i godzina z przesunięciem liczbowym. Funkcja honoruje przesunięcie i normalizuje wynik do UTC.
2. Data i godzina bez przesunięcia. Funkcja zakłada UTC.
3. Randka bez godziny. Funkcja zakłada północ UTC.

Poniższe przykłady pokazują, jak parse_timestamp obsługuje każdy typ wejścia.

Przekonwertowanie wartości epok Unix

Używaj from_epoch i to_epoch konwertuj między wartościami epoki Unix a znacznikami czasowymi RFC 3339.

from_epoch akceptuje wartości ujemne dla dat sprzed 1 stycznia 1970 roku. Jego wyjście ma precyzję milisekundową, więc przeliczenie mikrosekund epoki na znacznik czasu eliminuje precyzję poniżej jednej milisekundy. to_epoch uwzględnia przesunięcie UTC znacznika czasu i zaokrągla wartości sprzed 1970 roku do następnej niższej liczby całkowitej dla wybranej jednostki.

Można komponować funkcje daty i czasu. Na przykład oblicza duration_between($1, now(), "days") wiek w kilku dniach znacznika czasu RFC 3339 jako pierwszego wpisu reguły. Aby odczytać godzinę znacznika czasu po konwersji na UTC, użyj hour_of_day(from_epoch(to_epoch($1, "micros"), "micros")).

Funkcje warunkowe i kolekcji

Funkcje agregacji (tylko przekształcenia okien)

Te funkcje są dostępne tylko w regułach akumulacyjnych w ramach przekształceń okien. Każda z nich przyjmuje pojedynczą zmienną pozycyjną.

Aby uzyskać szczegółowe informacje na temat korzystania z funkcji agregacji, zobacz Agregowanie danych w czasie.

Logika warunkowa

if Użyj funkcji , aby rozgałęzić logikę w wyrażeniu:

Użyj () wartości (pustej) w porównaniach, aby wykryć brakujące pola.

Pola metadanych

Odczytywanie i zapisywanie metadanych komunikatów przy użyciu prefiksu $metadata. w inputs polach lub output reguły. Odwołania do metadanych idą w ścieżce pola, a nie w samym wyrażeniu.

Właściwości metadanych

• Temat: działa zarówno w przypadku MQTT, jak i platformy Kafka. Zawiera on ciąg, w którym opublikowano komunikat. Przykład: $metadata.topic.
• Właściwość użytkownika: W MQTT odnosi się to do par klucz/wartość dowolnej postaci, które może przenosić komunikat MQTT. Jeśli na przykład komunikat MQTT został opublikowany z właściwością użytkownika z kluczem "priority" i wartością "high", $metadata.user_property.priority odwołanie zawiera wartość "high". Klucze właściwości użytkownika mogą być dowolnymi ciągami i mogą wymagać ucieczki: $metadata.user_property."weird key" używa klucza "dziwnego klucza" (z spacją).
• Właściwość systemowa: ten termin jest używany dla każdej właściwości, która nie jest właściwością użytkownika. Obecnie obsługiwana jest tylko jedna właściwość systemu: $metadata.system_property.content_type, która odczytuje właściwość typu zawartości komunikatu MQTT (jeśli ustawiono).
• Nagłówek: To odpowiednik właściwości użytkownika MQTT w systemie Kafka. Platforma Kafka może używać dowolnej wartości binarnej dla klucza, ale przepływy danych obsługują tylko klucze ciągów UTF-8. Przykład: $metadata.header.priority. Ta funkcja jest podobna do właściwości użytkownika.

Odczyt z metadanych

Aby odwołać się do tematu źródłowego i właściwości użytkownika w wyrażeniu, wyświetl je jako dane wejściowe:

Wyrażenie: $1 + "/" + $2

W poniższym przykładzie właściwość MQTT topic jest mapowana do pola origin_topic w danych wyjściowych.

Jeśli właściwość priority użytkownika znajduje się w komunikacie MQTT, w poniższym przykładzie pokazano, jak mapować ją na pole wyjściowe:

Zapisywanie w metadanych

Aby ustawić właściwość użytkownika w komunikacie wyjściowym, użyj $metadata.user_property.<key> jako pola wyjściowego.

Ustawienie pola metadanych na wartość pustą (()) powoduje jego usunięcie. W przypadku właściwości użytkownika dozwolone są zduplikowane klucze.

Właściwości metadanych można również mapować na nagłówek danych wyjściowych lub właściwość użytkownika. W poniższym przykładzie MQTT topic jest mapowany na pole origin_topic we właściwości użytkownika wyniku.

Jeśli przychodzący ładunek zawiera priority pole, w poniższym przykładzie pokazano, jak mapować go na właściwość użytkownika MQTT:

Ten sam przykład dla platformy Kafka:

Pola metadanych są obsługiwane w regułach mapowania, filtrowania i gałęzi. Nie są one dostępne w regułach okna (akumulacja).

Ostatnia znana wartość

Użyj sufiksu ? $last danych wejściowych, aby poinformować środowisko uruchomieniowe o zapamiętaniu najnowszej wartości dla tego pola. Jeśli w bieżącym komunikacie brakuje pola, zostanie użyta ostatnia znana wartość.

Dyrektywa ? $last nie uwzględnia wielkości liter i obsługuje elastyczne odstępy.

Ostatnia znana wartość jest obsługiwana w regułach mapowania, filtrowania i gałęzi. Nie jest ona dostępna w regułach okna (akumulacja).

Wartości domyślne

Użyj sufiksu ?? <default> danych wejściowych, aby podać wartość rezerwową, gdy brakuje pola. Obsługiwane typy domyślne: liczba całkowita, zmiennoprzecinkowa, wartość logiczna, ciąg i wartość null.

Łączenie ostatniej znanej wartości i wartości domyślnej

Możesz połączyć ? $last elementy i ?? <default>. Środowisko uruchomieniowe najpierw sprawdza bieżący komunikat, a następnie ostatnią znaną wartość, a następnie wartość domyślną. Jeśli używasz ?? <default> polecenia bez ? $last, środowisko uruchomieniowe sprawdza bieżący komunikat, a następnie jest to ustawienie domyślne bezpośrednio.

Wartości domyślne są obsługiwane w regułach mapowania, filtrowania i gałęzi. Nie są one dostępne w regułach okna (akumulacja).

Typy danych

Obiekty i tablice JSON są zachowywane as-is podczas kopiowania pól bez wyrażenia, ale nie można ich używać jako danych wejściowych do oceny wyrażeń.

Obsługa funkcji według typu przekształcenia

Ten sam język wyrażeń działa na transformacjach, ale wynik wyrażenia oznacza coś innego w każdej z nich:

¹ Dostępne tylko w wykresach przepływu danych. Nieobsługiwane w danych wejściowych przepływu builtInTransformation danych.

Notacja kropkowa i ucieczka

Notacja kropkowa jest powszechnie używana do odwołowywania się do zagnieżdżonych pól. Standardowa ścieżka notacji kropkowej wygląda następująco: Person.Address.Street.Number.

W przepływie danych ścieżka opisana przez notację kropkową może zawierać ciągi i niektóre znaki specjalne bez konieczności ucieczki, takich jak Person.Date of Birth.

W innych przypadkach ucieczka jest niezbędna, na przykład: nsu=http://opcfoundation.org/UA/Plc/Applications;s=RandomSignedInt32. Ta ścieżka, między innymi znakami specjalnymi, zawiera kropki w nazwie pola. Bez ucieczki nazwa pola będzie służyć jako separator w notacji kropkowej.

Przepływ danych analizuje ścieżkę, ale traktuje tylko dwa znaki jako specjalne:

• Kropki (.) działają jako separatory pól.
• Podwójne cudzysłowy, umieszczone na początku lub końcu segmentu, rozpoczynają sekcję z ucieczką, gdzie kropki nie są traktowane jako separatory pól.

Wszystkie inne znaki są traktowane jako część nazwy pola. Ta elastyczność jest przydatna w formatach, takich jak JSON, gdzie nazwy pól mogą być dowolnymi ciągami.

Definicja ścieżki musi być również zgodna z regułami formatu konfiguracji. Gdy znak ze specjalnym znaczeniem jest zawarty w ścieżce, wymagane jest prawidłowe cudzysłów. Na przykład nazwy pól rozpoczynające się dwukropkiem (na :Person:.:name:przykład ) lub rozpoczynające się od liczby, po której następuje tekst (na przykład 100 celsius.hot), muszą być poprawnie interpretowane jako ciągi.

Ucieczki

Podstawową funkcją ucieczki w ścieżce kropkowanej jest zastosowanie kropek, które są częścią nazw pól, a nie separatorów. Na przykład ścieżka Payload."Tag.10".Value składa się z trzech segmentów: Payload, Tag.10i Value. Znaki podwójnego cudzysłowu Tag.10 wokół uniemożliwiają działanie kropki jako separatora.

Ucieczka reguł w notacji kropkowej

• Każdy segment potraktować oddzielnie: jeśli wiele segmentów zawiera znaki interpunkcyjne, te segmenty muszą być ujęte w podwójny cudzysłów. Można również cytować inne segmenty, ale nie ma to wpływu na interpretację ścieżki. Przykład: Payload."Tag.10".Measurements."Vibration.$12".Value

• Cytuj fragment tylko wtedy, gdy trzeba się z niego uwolnić. Podwójne cudzysłowy wokół segmentu należy dodawać tylko wtedy, gdy zawiera kropkę (lub inny znak, który w przeciwnym razie byłby błędnie odczytany jako separator). Nie cytuj zwykłej nazwy pola.

  Na przykład, dla pola nazwanego TagName wewnątrz Records:

  Wykonaj to	Nie to
  Records.TagName	Records."TagName"

  Dodatkowe cudzysłowy nie pomagają, a w niektórych narzędziach, takich jak edytor przepływu danych Operations Experience, stają się one częścią nazwy pola. Mapowanie szuka wtedy pola o nazwie "TagName" (z cudzysłowami), które nie istnieje, więc nic się nie zgadza. Można to zauważyć w definicji przepływu eksportowanych danych, gdzie nazwa pojawia się z cudzysłowami z ucieczki, np \"TagName\". . Aby to naprawić, usuń cudzysłów, tak aby nazwa to po prostu TagName.

• Prawidłowe użycie podwójnych cudzysłowów: podwójny cudzysłów musi otwierać i zamykać segment ucieczki. Wszelkie cudzysłów w środku segmentu są traktowane jako część nazwy pola. Na przykład ścieżka Payload.He said: "Hello", and waved definiuje dwa pola: Payload i He said: "Hello", and waved. Gdy kropka pojawi się w tych okolicznościach, nadal służy jako separator. Na przykład ścieżka Payload.He said: "No. It is done" jest podzielona na segmenty Payload, He said: "Noi It is done" (począwszy od spacji).

Algorytm segmentacji

• Jeśli pierwszy znak segmentu jest znakiem cudzysłowu, analizator wyszukuje następny cudzysłów. Ciąg ujęty między tymi cudzysłowami jest traktowany jako pojedynczy segment.
• Jeśli segment nie zaczyna się od cudzysłowu, analizator identyfikuje segmenty, wyszukując następną kropkę lub koniec ścieżki.

Symbole wieloznaczne

Użyj symbolu wieloznakowego (*) w ścieżkach wejściowych i wyjściowych, aby dopasować wiele pól jednocześnie. Jest to przydatne, gdy dane wyjściowe są dokładnie podobne do danych wejściowych lub gdy trzeba zastosować tę samą transformację w wielu polach bez wyświetlania listy każdego z nich.

Kopiowanie wszystkich pól

Aby przekazać każde pole bez zmian:

Dopasuj * każdą ścieżkę pola do danych wejściowych i umieszcza ją w tej samej ścieżce w danych wyjściowych. Część pasujących ścieżek * jest nazywana przechwyconym segmentem. W danych wyjściowych przechwycony segment zastępuje element *.

Spłaszczane pola zagnieżdżone

Aby przenieść pola z zagnieżdżonego obiektu do poziomu głównego, umieść prefiks w danych wejściowych i * w danych wyjściowych:

Biorąc pod uwagę te dane wejściowe:

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

Dane wyjściowe spłaszczają oba obiekty:

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

Przebuduj pola

Aby przenieść pola pod nowym elementem nadrzędnym, umieść * w danych wejściowych i dodaj prefiks w danych wyjściowych:

To opakowuje wszystkie pola najwyższego Telemetry poziomu wewnątrz obiektu.

Reguły umieszczania symboli wieloznacznych

• Tylko jedna* jest dozwolona dla ścieżki wejściowej lub wyjściowej.
• Element * musi być zgodny z kompletnym segmentem (a nie segmentem częściowym, np Sensor*. ).
• Element * może pojawić się na początku (*.Value), środkowym (Sensors.*.Reading) lub na końcuSensors.* () ścieżki.

Symbole wieloznaczne z wieloma wejściami

Jeśli reguła ma wiele danych wejściowych z symbolami wieloznacznymi, * element musi przechwytywać ten sam segment we wszystkich danych wejściowych. Środowisko uruchomieniowe rozpoznaje element * z pierwszych danych wejściowych, a następnie wyszukuje pasujące ścieżki w innych danych wejściowych.

Aby na przykład średnią maksymalną i minimalną liczbę odczytów dla każdego czujnika:

Biorąc pod uwagę te dane wejściowe:

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

Najpierw przechwytuje * element , więc reguła Temperature szuka wartości i Temperature.MaxTemperature.Min. Następnie przechwytuje Pressure i szuka Pressure.Max i Pressure.Min. Dane wyjściowe to:

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

Jeśli jakiekolwiek dane wejściowe nie mogą rozpoznać przechwyconego segmentu (na przykład *.Mid.Avg gdy pole jest zagnieżdżone inaczej), ten segment jest pomijany. Upewnij się, że ścieżki we wszystkich danych wejściowych odzwierciedlają rzeczywistą strukturę danych.

Zastąpij symbol wieloznaczny dla określonych pól

Możesz połączyć regułę z symbolami wieloznacznymi z określonymi regułami. Określone reguły mają pierwszeństwo, gdy mają niższe pokrycie (mniej segmentów dopasowanych przez *element ). Jest to nazywane specjalizacją.

Pierwsza reguła dotyczy wszystkich pól. Druga reguła zastępuje ją tylko, Pressure ponieważ Pressure.Max jest bardziej szczegółowa niż *.Max (pokrycie 0 a pokrycie 1).

Aby całkowicie wykluczyć pole, użyj pustych danych wyjściowych:

Puste dane wyjściowe pomiń pole z wyniku. Spowoduje to zastąpienie dowolnej reguły z symbolami wieloznacznymi, która w przeciwnym razie będzie ją uwzględniać.

Wiele reguł dotyczących tych samych danych wejściowych

Jeśli dwie reguły mają takie samo lub wyższe pokrycie, oba mają zastosowanie. Dzięki temu można obliczyć wiele wartości pochodnych z tych samych danych wejściowych:

Obie reguły są wykonywane dla każdego przechwyconego segmentu, tworząc dwa pola wyjściowe na czujnik.

Symbole wieloznaczne w zestawach danych kontekstowych

Możesz użyć symboli wieloznacznych z $context odwołaniami, aby skopiować wszystkie pola z zestawu danych:

Spowoduje to skopiowanie każdego pola z assetMeta zestawu danych do Asset sekcji danych wyjściowych.

Zestawy danych kontekstowych

Zestawy danych kontekstowych umożliwiają mapowanie integrowania dodatkowych danych z zewnętrznych baz danych. Użyj prefiksu $context(datasetName) , aby odwołać się do pól z zestawu danych. Na przykład $context(position).BaseSalary odczytuje BaseSalary pole z zestawu danych o nazwie position.

Aby uzyskać szczegółowe informacje na temat konfigurowania zestawów danych kontekstowych, zobacz Wzbogacanie danych przy użyciu przepływów danych i Wzbogacanie o dane zewnętrzne na wykresach przepływu danych.

Treści powiązane

Jeśli przyszedłeś tutaj szukając składni użytej w konkretnej transformacji, te artykuły pokazują wyrażenia w kontekście:

Dla przepływów danych zobacz Mapowanie danych poprzez wykorzystanie przepływów danych oraz Filtrowanie danych w przepływie danych.