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. Korzystając z bogatego zestawu metod String, RegExp, Math, Array i Date , które oferuje JavaScript, możesz tworzyć złożone transformacje danych w zadaniach Stream Analytics. Funkcje definiowane przez użytkownika w języku JavaScript umożliwiają tworzenie bezstanowych, wyłącznie obliczeniowych funkcji skalarnych, które nie wymagają zewnętrznej łączności. 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.

Ten artykuł opisuje, kiedy korzystać z funkcji zdefiniowanych przez użytkownika w JavaScript oraz jak je definiować i wywoływać w swoich zadaniach związanych ze Stream Analytics.

Kiedy używać funkcji zdefiniowanej przez użytkownika w JavaScript

Poniżej przedstawiono kilka scenariuszy, w których funkcje języka JavaScript zdefiniowane przez użytkownika mogą być przydatne:

  • Parsowanie i manipulowanie ciągami znaków za pomocą funkcji wyrażeń regularnych, na przykład Regexp_Replace() i Regexp_Extract()
  • Dekodowanie i kodowanie danych, na przykład konwersja z systemu binarnego na szesnastkowy
  • Wykonywanie obliczeń matematycznych z wykorzystaniem funkcji matematycznych JavaScript
  • Wykonywanie operacji tablicy, takich jak sortowanie, sprzężenie, znajdowanie i wypełnianie

Oto kilka rzeczy, których nie da się zrobić, używając funkcji zdefiniowanej przez użytkownika JavaScript w Stream Analytics:

  • Na przykład wywołaj zewnętrzne punkty końcowe REST, wykonując odwrotne wyszukiwanie IP lub pobierając dane referencyjne z zewnętrznego źródła
  • Wykonaj niestandardową serializację lub deserializację formatu zdarzeń dla danych wejściowych lub wyjściowych
  • Utwórz niestandardowe agregaty

Chociaż funkcje takie jak Date.GetDate() czy Math.random() nie są zablokowane w definicji funkcji, unikaj 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 te same zdarzenia, powtarzalność nie jest gwarantowana, gdy ty lub usługa Stream Analytics wznawiacie zadanie.

Zdefiniuj funkcję zdefiniowaną przez użytkownika w JavaScript w portalu Azure

Dla zadania Stream Analytics działającego w chmurze, dodaj funkcję zdefiniowaną przez użytkownika JavaScript ze strony Funkcje w sekcji Job Topology, gdzie menu +Add zawiera opcję JavaScript UDF .

Uwaga

To doświadczenie dotyczy zadań Stream Analytics skonfigurowanych do pracy w chmurze. Jeśli zadanie usługi Stream Analytics jest skonfigurowane do uruchamiania w usłudze Azure IoT Edge, zamiast tego użyj programu Visual Studio i napisz funkcję zdefiniowaną przez użytkownika przy użyciu języka C#.

Zrzut ekranu strony Functions w portalu Azure, pokazująca menu Dodaj z opcją JavaScript UDF.

Definicja funkcji składa się z następujących właściwości:

Właściwości Opis
Alias funkcji Nazwa, która wywołuje funkcję w twoim zapytaniu.
Typ danych wyjściowych Typ, który funkcja JavaScript zdefiniowana przez użytkownika zwraca do zapytania Stream Analytics.
Definicja funkcji Implementacja funkcji JavaScript, która uruchamia się za każdym razem, gdy UDF jest wywoływany z Twojego zapytania.

Testowanie i rozwiązywanie problemów z logiką JavaScript UDF

Ponieważ portal Stream Analytics nie obsługuje debugowania i testowania logiki tych funkcji zdefiniowanych przez użytkownika, możesz testować i debugować logikę JavaScript UDF w dowolnej przeglądarce. Gdy funkcja działa zgodnie z oczekiwaniami, jest gotowa do dodania do zadania Stream Analytics i wywołania bezpośrednio z Twojego zapytania. Możesz także przetestować logikę zapytań za pomocą JavaScript UDF, korzystając z narzędzi Stream Analytics dla Visual Studio.

Stream Analytics traktuje błędy wykonawcze JavaScript jako śmiertelne i pokazuje je w dzienniku aktywności. Log jest dostępny w portalu Azure na stronie dziennika aktywności Twojego zadania.

Wywoływanie funkcji w języku JavaScript zdefiniowanej przez użytkownika w zapytaniu

Aby wywołać funkcję JavaScript w zapytaniu, użyj aliasu funkcji z prefiksem udf. Poniższy przykład przedstawia funkcję UDF języka JavaScript, która konwertuje wartości szesnastkowe na liczbę całkowitą w zapytaniu Stream Analytics.

    SELECT
        time,
        UDF.hex2Int(offset) AS IntOffset
    INTO
        output
    FROM
        InputStream

Obsługiwane obiekty języka JavaScript

Funkcje zdefiniowane przez użytkownika w języku JavaScript w usłudze Azure Stream Analytics obsługują standardowe, wbudowane obiekty języka JavaScript. Te obiekty dają Twoim funkcjom dostęp do wspólnych operacji ciągowych, matematycznych, tablicowych i datowych bez dodatkowej konfiguracji. Pełną listę dostępnych obiektów można znaleźć w sekcji Obiekty globalne. Ponieważ język zapytań Stream Analytics i JavaScript nie korzystają z tego samego systemu typów, Stream Analytics konwertuje wartości w miarę ich przekazywania.

Konwersja typów w usłudze Stream Analytics i w języku JavaScript

Język zapytań Stream Analytics oraz JavaScript obsługują różne typy. Ta tabela zawiera odwzorowania konwersji między nimi:

analiza strumienia 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)
podwójna precyzja Liczba
nvarchar(MAX) String
Nagrywanie Objekt
Tablica Tablica
NULL Null

W tym miejscu przedstawiono konwersje typów języka JavaScript na typy usługi Stream Analytics:

JavaScript analiza strumienia
Liczba Bigint (jeśli liczba jest zaokrąglona i należy do zakresu long.MinValue-long.MaxValue; w przeciwnym razie to double)
Date DateTime
String nvarchar(MAX)
Objekt Rekord
Tablica Tablica
Zerowe, nieokreślone NULL
Każdy inny typ (na przykład funkcja lub błąd) Nieobsługiwane (powoduje wystąpienie błędu w czasie wykonywania)

JavaScript rozróżnia wielkość liter, a wielkość liter w nazwach pól obiektu w kodzie JavaScript musi odpowiadać wielkości liter w nazwach pól w danych przychodzących. Zadania z poziomem zgodności 1.0 konwertują pola z instrukcji SQL SELECT na małe litery. Na poziomie zgodności 1.1 i wyższym pola z instrukcji SELECT mają takie samo oznaczenie jak w zapytaniu SQL.

Typowe wzorce funkcji

Poniższe wzorce pokazują powszechne sposoby wykorzystania funkcji zdefiniowanych przez użytkownika JavaScript do transformacji danych w zapytaniach Stream Analytics. Każdy wzorzec zawiera definicję funkcji oraz przykładowe zapytanie, które go wywołuje.

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. Poniższa definicja funkcji wywołuje funkcję JSON.stringify(), aby spakować wszystkie pary nazwa/wartość wejścia, a następnie zapisać je jako pojedynczą wartość ciągu w wyjściowym wydaniu.

function main(x) {
return JSON.stringify(x);
}

Zapytanie Stream Analytics wywołuje funkcję, jak pokazano w poniższym przykładzie.

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 znakowe będące JSON i chcesz je przekonwertować na obiekt JSON do przetwarzania w JavaScript UDF, możesz użyć funkcji JSON.parse(), aby utworzyć obiekt JSON, który następnie możesz użyć. Poniższa definicja funkcji analizuje ciąg i zwraca właściwość z powstałego obiektu.

function main(x) {
var person = JSON.parse(x);  
return person.name;
}

Zapytanie Stream Analytics wywołuje funkcję, jak pokazano w poniższym przykładzie.

SELECT
    UDF.getName(input) AS Name
INTO
    output
FROM
    input

Używanie funkcji try/catch do obsługi błędów

Bloki try/catch mogą pomóc zidentyfikować problemy z nieprawidłowo ukształtowanymi danymi wejściowymi, które przekazujesz do JavaScript UDF. Poniższa definicja funkcji wykorzystuje blok try/catch do obsługi błędów parsowania.

function main(input, x) {
    var obj = null;

    try{
        obj = JSON.parse(x);
    }catch(error){
        throw input;
    }
    
    return obj.Value;
}

W poniższym przykładowym zapytaniu przekazujesz cały rekord jako pierwszy parametr, aby funkcja mogła go zwrócić w przypadku 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 systemie JavaScript zwraca ciąg językowy wrażliwy na język, który reprezentuje dane daty-czasu z miejsca, z którego wywołujesz metodę. Mimo że Azure Stream Analytics akceptuje tylko UTC datę-czas jako znacznik czasu systemowego, możesz użyć tej metody do konwersji znacznika czasu systemu na inną lokalizację i strefę czasową. Ta metoda stosuje takie samo zachowanie implementacyjne jak ta dostępna w Internet Explorer. Poniższa definicja funkcji przekształca czas daty wejściowej na lokalizację de-DE .

function main(datetime){
    const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
    return datetime.toLocaleDateString('de-DE', options);
}

W poniższym przykładowym zapytaniu jako wartość wejściową przekazywana jest wartość datetime.

SELECT
    udf.toLocaleString(input.datetime) as localeString
INTO
    output
FROM
    input

Wynikiem tego zapytania jest wejściowa data i godzina w formacie de-DE z podanymi opcjami.

Samstag, 28. December 2019

Rejestrowanie użytkowników

Logowanie to mechanizm, którego Azure Stream Analytics wykorzystuje do przechwytywania niestandardowych informacji z funkcji zdefiniowanej przez użytkownika JavaScript podczas działania zadania. Ponieważ uruchomione zadanie jest poza tym trudne do obserwacji, dzienniki zapewniają wgląd w zachowanie i poprawność własnego kodu w czasie rzeczywistym. Każda wiadomość w dzienniku zawiera poziom zdarzenia, który wskazuje, jak ważna jest wiadomość i czy zadanie może działać dalej.

Komunikaty informacyjne pochodzą z metody console.info(), takie jak console.info('my info message');. Ten poziom rejestruje ogólne informacje podczas wykonywania i nie przerywa obliczeń. Komunikaty ostrzegawcze pochodzą z metody console.warn(), takie jak console.warn('my warning message');. Ten poziom rejestruje dane, które mogą być nieoczekiwane, ale nadal są akceptowalne do obliczeń, więc zadanie jest kontynuowane. Komunikaty o błędach pochodzą z metod console.error() i console.log(), takich jak console.error('my error message');. Te metody dotyczą tylko sytuacji, gdy kod nie może kontynuować, więc wyrzucają wyjątek z dostarczonymi informacjami o błędzie i zatrzymują zadanie.

Dostęp do komunikatów dziennika można uzyskać za pośrednictwem dzienników diagnostycznych.

atob() i btoa()

Analiza strumieni obsługuje dwie metody konwersji Base64, co jest powszechnym sposobem kodowania danych binarnych jako tekstu. Metoda btoa() koduje ciąg ASCII w Base64, a metoda atob() dekoduje ciąg danych kodowanych w Base64 z powrotem do ciągu ASCII. W poniższym przykładzie koduje btoa() ciąg ASCII, a atob() następnie dekoduje wynik z powrotem do oryginalnego ciągu znaków.

var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);

Treści powiązane

  • Last updated on