Funkcje zdefiniowane przez użytkownika w języku JavaScript w usłudze Azure Stream Analytics
Usługa Azure Stream Analytics obsługuje funkcje zdefiniowane przez użytkownika, które napisano w języku JavaScript. Dzięki rozbudowanym zestawom metod String, RegExp, Math, Array i Date zapewnianych przez język JavaScript złożone przekształcenia danych za pomocą zadań usługi Stream Analytics stają się łatwiejsze do utworzenia.
Omówienie
Funkcje zdefiniowane przez użytkownika w języku JavaScript obsługują funkcje bezstanowe, tylko obliczeniowe, które nie wymagają łączności zewnętrznej. Wartość zwracana przez funkcję może być tylko wartością skalarną (pojedynczą). Po dodaniu funkcji języka JavaScript zdefiniowanej przez użytkownika do zadania możesz jej używać we wszystkich miejscach zapytania — tak jak wbudowanej funkcji skalarnej.
Poniżej przedstawiono kilka scenariuszy, w których funkcje języka JavaScript zdefiniowane przez użytkownika mogą być przydatne:
- Analizowanie ciągów zawierających funkcje do obsługi wyrażeń regularnych, na przykład Regexp_Replace() i Regexp_Extract(), oraz wykonywanie operacji na takich ciągach
- Dekodowanie i kodowanie danych, na przykład konwersja danych binarnych na szesnastkowe
- Wykonywanie obliczeń matematycznych za pomocą funkcji matematycznych w języku JavaScript
- Wykonywanie operacji tablicowych, takich jak sortowanie, sprzężenie, znajdowanie i wypełnianie
Oto kilka rzeczy, których nie można wykonać za pomocą funkcji zdefiniowanej przez użytkownika w języku JavaScript w usłudze Stream Analytics:
- Wywoływanie zewnętrznych punktów końcowych REST, na przykład wykonywanie wyszukiwania odwrotnego adresu IP lub ściąganie danych referencyjnych ze źródła zewnętrznego
- Wykonywanie niestandardowej serializacji lub deserializacji formatu zdarzeń dla danych wejściowych lub wyjściowych
- Tworzenie niestandardowych wartości zagregowanych
Chociaż funkcje takie jak Date.GetDate() lub Math.random() nie są blokowane w definicji funkcji, należy unikać ich używania. Te funkcje nie zwracają tego samego wyniku za każdym razem, gdy je wywołujesz, a usługa Azure Stream Analytics nie przechowuje dziennika wywołań funkcji i zwracanych wyników. Jeśli funkcja zwraca inny wynik na tych samych zdarzeniach, powtarzalność nie jest gwarantowana, gdy zadanie zostanie uruchomione ponownie przez Ciebie lub przez usługę Stream Analytics.
Dodawanie funkcji zdefiniowanej przez użytkownika w języku JavaScript do zadania
Uwaga
Te kroki działają nad zadaniami usługi Stream Analytics skonfigurowanymi do uruchamiania w chmurze. Jeśli zadanie usługi Stream Analytics jest skonfigurowane do uruchamiania na platformie Azure IoT Edge, zamiast tego użyj programu Visual Studio i napisz funkcję zdefiniowaną przez użytkownika przy użyciu języka C#.
Aby utworzyć funkcję zdefiniowaną przez użytkownika w języku JavaScript w zadaniu usługi Stream Analytics, wybierz pozycję Funkcje w obszarze Topologia zadań. Następnie wybierz pozycję JavaScript UDF z menu rozwijanego +Dodaj .
Następnie należy podać następujące właściwości i wybrać pozycję Zapisz.
| Właściwość | Opis |
|---|---|
| Alias funkcji | Wprowadź nazwę, aby wywołać funkcję w zapytaniu. |
| Typ danych wyjściowych | Typ, który zostanie zwrócony przez funkcję zdefiniowaną przez użytkownika w języku JavaScript do zapytania usługi Stream Analytics. |
| Definicja funkcji | Implementacja funkcji JavaScript, która będzie wykonywana za każdym razem, gdy funkcja UDF zostanie wywołana z zapytania. |
Testowanie i rozwiązywanie problemów z funkcjami zdefiniowanymi przez użytkownika w języku JavaScript
Logikę UDF języka JavaScript można przetestować i debugować w dowolnej przeglądarce. Debugowanie i testowanie logiki tych funkcji zdefiniowanych przez użytkownika nie jest obecnie obsługiwane w portalu usługi Stream Analytics. Gdy funkcja działa zgodnie z oczekiwaniami, możesz dodać ją do zadania usługi Stream Analytics, jak wspomniano powyżej, a następnie wywołać ją bezpośrednio z zapytania. Logikę zapytań można przetestować za pomocą funkcji UDF języka JavaScript przy użyciu narzędzi usługi Stream Analytics dla programu Visual Studio.
Błędy w czasie wykonywania kodu JavaScript są traktowane jako błędy krytyczne i uwidaczniane w dzienniku aktywności. Aby pobrać dziennik, w witrynie Azure Portal przejdź do zadania i wybierz pozycję Dziennik aktywności.
Wywoływanie funkcji w języku JavaScript zdefiniowanej przez użytkownika w zapytaniu
Funkcję Języka JavaScript można łatwo wywołać w zapytaniu przy użyciu aliasu funkcji poprzedzonego prefiksem udf. Oto przykład funkcji UDF języka JavaScript, która konwertuje wartości szesnastkowe na liczbę całkowitą wywoływaną w zapytaniu usługi Stream Analytics.
SELECT
time,
UDF.hex2Int(offset) AS IntOffset
INTO
output
FROM
InputStream
Obsługiwane obiekty języka JavaScript
Funkcje języka JavaScript zdefiniowane przez użytkownika w usłudze Azure Stream Analytics obsługują standardowe wbudowane obiekty języka JavaScript. Aby uzyskać listę tych obiektów, zobacz artykuł Global Objects (Obiekty globalne).
Konwersja typów usługi Stream Analytics i języka JavaScript
Między typami obsługiwanymi przez język zapytań usługi Stream Analytics i język JavaScript występują różnice. Poniższa tabela zawiera mapowania konwersji między typami:
| Stream Analytics | JavaScript |
|---|---|
| bigint | Number (maksymalna liczba całkowita, która może być reprezentowana przez język JavaScript, to 2^53) |
| DateTime | Date (język JavaScript obsługuje tylko milisekundy) |
| double | Liczba |
| nvarchar(MAX) | Ciąg |
| Rekord | Obiekt |
| Tablica | Tablica |
| NULL | Null |
W tym miejscu przedstawiono konwersje typów języka JavaScript na typy usługi Stream Analytics:
| JavaScript | Stream Analytics |
|---|---|
| Liczba | Bigint (jeśli liczba jest zaokrąglona i należy do zakresu long.MinValue-long.MaxValue; w przeciwnym razie to double) |
| Date | DateTime |
| Ciąg | nvarchar(MAX) |
| Obiekt | Rekord |
| Tablica | Tablica |
| Null, Undefined | NULL |
| Każdy inny typ (na przykład function lub error) | Nieobsługiwane (powoduje wystąpienie błędu w czasie wykonywania) |
Język JavaScript ma wielkość liter i wielkość liter pól obiektu w kodzie JavaScript musi być zgodna z wielkością liter pól w danych przychodzących. Zadania z poziomem zgodności 1.0 przekonwertują pola z instrukcji SQL SELECT na małe litery. W obszarze poziom zgodności 1.1 i nowszych pola z instrukcji SELECT będą miały taką samą wielkość liter, jak określona w zapytaniu SQL.
Inne wzorce funkcji języka JavaScript zdefiniowanej przez użytkownika
Zapisywanie zagnieżdżonego kodu JSON do wyjścia
Jeśli stosujesz kolejny krok przetwarzania, który używa wyjścia zadania usługi Stream Analytics jako wejścia i wymaga formatu JSON, możesz zapisać ciąg JSON do wyjścia. W następnym przykładzie jest wywoływana funkcja JSON.stringify() w celu spakowania wszystkich par nazwa-wartość w danych wejściowych, a następnie zapisania ich w postaci pojedynczego ciągu do wyjścia.
Definicja funkcji języka JavaScript zdefiniowanej przez użytkownika:
function main(x) {
return JSON.stringify(x);
}
Przykładowe zapytanie:
SELECT
DataString,
DataValue,
HexValue,
UDF.jsonstringify(input) As InputEvent
INTO
output
FROM
input PARTITION BY PARTITIONID
Rzutowanie ciągu do obiektu JSON w celu przetworzenia
Jeśli masz pole ciągu, które jest plikiem JSON i chcesz przekonwertować je na obiekt JSON do przetwarzania w funkcji UDF w języku JavaScript, możesz użyć funkcji JSON.parse(), aby utworzyć obiekt JSON, którego można następnie użyć.
Definicja funkcji języka JavaScript zdefiniowanej przez użytkownika:
function main(x) {
var person = JSON.parse(x);
return person.name;
}
Przykładowe zapytanie:
SELECT
UDF.getName(input) AS Name
INTO
output
FROM
input
Używanie funkcji try/catch na potrzeby obsługi błędów
Bloki try/catch mogą pomóc w zidentyfikowaniu problemów z nieprawidłowo sformułowanymi danymi wejściowymi, które są przekazywane do funkcji zdefiniowanej przez użytkownika języka JavaScript.
Definicja funkcji języka JavaScript zdefiniowanej przez użytkownika:
function main(input, x) {
var obj = null;
try{
obj = JSON.parse(x);
}catch(error){
throw input;
}
return obj.Value;
}
Przykładowe zapytanie: przekaż cały rekord jako pierwszy parametr, aby można było go zwrócić w przypadku wystąpienia błędu.
SELECT
A.context.company AS Company,
udf.getValue(A, A.context.value) as Value
INTO
output
FROM
input A
toLocaleString()
Metoda toLocaleString w języku JavaScript może służyć do zwracania ciągu wrażliwego na język, który reprezentuje dane daty i godziny, z których jest wywoływana ta metoda. Mimo że usługa Azure Stream Analtyics akceptuje tylko datę UTC jako sygnaturę czasową systemu, ta metoda może służyć do pokrycia znacznika czasu systemu do innych ustawień regionalnych i strefy czasowej. Ta metoda jest zgodna z tym samym zachowaniem implementacji co metoda dostępna w programie Internet Explorer.
Definicja funkcji języka JavaScript zdefiniowanej przez użytkownika:
function main(datetime){
const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
return datetime.toLocaleDateString('de-DE', options);
}
Przykładowe zapytanie: przekazywanie daty/godziny jako wartości wejściowej
SELECT
udf.toLocaleString(input.datetime) as localeString
INTO
output
FROM
input
Dane wyjściowe tego zapytania będą danymi wejściowymi data/godzina w de-DE z podanymi opcjami.
Samstag, 28. Dezember 2019
Rejestrowanie użytkownika
Mechanizm rejestrowania umożliwia użytkownikom przechwytywanie niestandardowych informacji podczas wykonywania zadania. Dane dziennika mogą służyć do debugowania lub oceniania poprawności kodu niestandardowego w czasie rzeczywistym. Ten mechanizm jest dostępny za pośrednictwem trzech różnych metod.
Console.Info()
Console.Info metoda służy do rejestrowania ogólnych informacji podczas wykonywania kodu. Ta metoda będzie rejestrować dane bez przerywania obliczeń. Zarejestrowany komunikat zostanie oznaczony jako Informacyjny poziom zdarzenia.
console.info('my info message');
Console.Warn()
Metoda Console.Warn służy do rejestrowania danych, które mogą nie być poprawne lub oczekiwane, ale są nadal akceptowane do obliczeń. Ta metoda nie przerywa obliczeń i zostanie wznowiona po zwróceniu metody. Zarejestrowany komunikat zostanie oznaczony jako Ostrzeżenie na poziomie zdarzenia.
console.warn('my warning message');
Console.Error() i Console.Log()
Metoda Console.Error służy tylko do rejestrowania przypadków błędów, w których kod nie może kontynuować działania. Ta metoda zgłosi wyjątek z podanymi informacjami o błędzie, ponieważ parametr wejściowy i zadanie przestanie działać. Zarejestrowany komunikat o błędzie zostanie oznaczony jako Błąd poziomu zdarzeń.
console.error('my error message');
Dostęp do komunikatów dziennika można uzyskać za pośrednictwem dzienników diagnostycznych.
atob() i btoa()
Metoda btoa() może służyć do kodowania ciągu ASCII do base64. Zwykle odbywa się to w celu transferu danych w formacie binarnym. Metoda atob() może służyć do dekodowania ciągu danych zakodowanych w formacie Base64 do formatu ciągu ASCII.
var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);