Opracowywanie funkcji zdefiniowanych przez użytkownika platformy .NET Standard dla zadań usługi Azure Stream Analytics (wersja zapoznawcza)

  • Artykuł

Usługa Azure Stream Analytics oferuje język zapytań przypominający SQL do wykonywania przekształceń i obliczeń na strumieniach danych zdarzeń. Istnieje wiele wbudowanych funkcji, ale niektóre złożone scenariusze wymagają dodatkowej elastyczności. Za pomocą funkcji zdefiniowanych przez użytkownika (UDF) platformy .NET Standard można wywoływać własne funkcje napisane w dowolnym języku standardowym platformy .NET (C#, F#itp.), aby rozszerzyć język zapytań usługi Stream Analytics. Funkcje zdefiniowane przez użytkownika umożliwiają wykonywanie złożonych obliczeń matematycznych, importowanie niestandardowych modeli uczenia maszynowego przy użyciu ML.NET i używanie niestandardowej logiki imputacji w przypadku brakujących danych. Funkcja funkcji zdefiniowanej przez użytkownika dla zadań usługi Stream Analytics jest obecnie w wersji zapoznawczej i nie powinna być używana w obciążeniach produkcyjnych.

Regiony

Funkcja funkcji zdefiniowanej przez użytkownika platformy .NET jest włączona dla zadań w chmurze uruchamianych w klastrach usługi Stream Analytics. Zadania uruchamiane w jednostce SKU z wieloma dzierżawami w warstwie Standardowa mogą korzystać z tej funkcji w następujących regionach publicznych:

  • Zachodnio-środkowe stany USA
  • Europa Północna
  • East US
  • Zachodnie stany USA
  • Wschodnie stany USA 2
  • West Europe

Jeśli interesuje Cię użycie tej funkcji w innym regionie, możesz zażądać dostępu.

Ścieżka pakietu

Format dowolnego pakietu UDF ma ścieżkę /UserCustomCode/CLR/*. Biblioteki linków dynamicznych (DLL) i zasoby są kopiowane w folderze /UserCustomCode/CLR/* , co pomaga odizolować biblioteki DLL użytkowników od bibliotek DLL systemu i bibliotek DLL usługi Azure Stream Analytics. Ta ścieżka pakietu jest używana dla wszystkich funkcji niezależnie od metody użytej do ich zastosowania.

Obsługiwane typy i mapowania

Aby wartości usługi Azure Stream Analytics były używane w języku C#, należy przeprowadzić ich marshaling z jednego środowiska do drugiego. Przeprowadzanie marshalingu odbywa się dla wszystkich parametrów wejściowych funkcji zdefiniowanej przez użytkownika. Każdy typ usługi Azure Stream Analytics ma odpowiedni typ w języku C# pokazanym w poniższej tabeli:

Typ usługi Azure Stream Analytics Typ języka C#
bigint długi
float double
Nvarchar(max) ciąg
datetime DateTime
Rekord Ciąg słownika<, obiekt>
Tablica Object[]

To samo dotyczy sytuacji, gdy dane muszą być przesłożone z języka C# do usługi Azure Stream Analytics, co ma miejsce w przypadku wartości wyjściowej funkcji zdefiniowanej przez użytkownika. W poniższej tabeli przedstawiono obsługiwane typy:

Typ języka C# Typ usługi Azure Stream Analytics
długi bigint
double float
ciąg Nvarchar(max)
DateTime Data i godzina
struktura Rekord
object Rekord
Object[] Tablica
Ciąg słownika<, obiekt> Rekord

Opracowywanie funkcji zdefiniowanej przez użytkownika w usłudze Visual Studio Code

Visual Studio Code narzędzia usługi Azure Stream Analytics ułatwiają pisanie funkcji zdefiniowanych przez użytkownika, testowanie zadań lokalnie (nawet w trybie offline) i publikowanie zadania usługi Stream Analytics na platformie Azure.

Istnieją dwa sposoby implementowania standardowych funkcji zdefiniowanych przez użytkownika platformy .NET w narzędziach Visual Studio Code.

  • Funkcje zdefiniowane przez użytkownika z lokalnych bibliotek DLL
  • Funkcje zdefiniowane przez użytkownika z projektu lokalnego

Projekt lokalny

Funkcje zdefiniowane przez użytkownika można napisać w zestawie, do którego później odwołuje się zapytanie usługi Azure Stream Analytics. Jest to zalecana opcja dla złożonych funkcji, które wymagają pełnej mocy języka .NET Standard poza językiem wyrażeń, takim jak logika proceduralna lub rekursja. Funkcje zdefiniowane przez użytkownika z projektu lokalnego mogą być również używane, gdy trzeba udostępnić logikę funkcji w kilku zapytaniach usługi Azure Stream Analytics. Dodawanie funkcji zdefiniowanych przez użytkownika do projektu lokalnego umożliwia lokalne debugowanie i testowanie funkcji.

Aby odwołać się do projektu lokalnego:

  1. Utwórz nową bibliotekę klas standardowych platformy .NET na komputerze lokalnym.
  2. Napisz kod w klasie. Należy pamiętać, że klasy muszą być zdefiniowane jako publiczne , a obiekty muszą być zdefiniowane jako statyczne publiczne.
  3. Dodaj nowy plik konfiguracji funkcji CSharp w projekcie usługi Azure Stream Analytics i odwołaj się do projektu biblioteki klas CSharp.
  4. Skonfiguruj ścieżkę zestawu w pliku konfiguracji zadania , JobConfig.jsonsekcji CustomCodeStorage . Ten krok nie jest wymagany do testowania lokalnego.

Lokalne biblioteki DLL

Możesz również odwoływać się do lokalnych bibliotek DLL, które zawierają funkcje zdefiniowane przez użytkownika.

Przykład

W tym przykładzie CSharpUDFProject jest projektem biblioteki klas języka C#, a ASAUDFDemo to projekt usługi Azure Stream Analytics, który będzie odwoływać się do projektu CSharpUDFProject.

Projekt usługi Azure Stream Analytics w Visual Studio Code

Następująca funkcja zdefiniowana przez użytkownika ma funkcję, która mnoży liczbę całkowitą przez siebie w celu utworzenia kwadratu liczby całkowitej. Klasy muszą być zdefiniowane jako publiczne , a obiekty muszą być zdefiniowane jako statyczne publiczne.

using System;

namespace CSharpUDFProject
{
    // 
    public class Class1
    {
        public static Int64 SquareFunction(Int64 a)
        {
            return a * a;
        }
    }
}

W poniższych krokach pokazano, jak dodać funkcję UDF języka C# do projektu usługi Stream Analytics.

  1. Kliknij prawym przyciskiem myszy folder Funkcje i wybierz polecenie Dodaj element.

    Dodawanie nowej funkcji w projekcie usługi Azure Stream Analytics

  2. Dodaj funkcję języka C# SquareFunction do projektu usługi Azure Stream Analytics.

    Wybieranie funkcji CSharp z projektu usługi Stream Analytics w programie VS Code

    Wprowadź nazwę funkcji CSharp w programie VS Code

  3. W konfiguracji funkcji języka C# wybierz pozycję Wybierz ścieżkę projektu biblioteki , aby wybrać projekt C# z listy rozwijanej, a następnie wybierz pozycję Kompiluj projekt , aby skompilować projekt. Następnie wybierz pozycję Wybierz klasę i Wybierz metodę , aby wybrać powiązaną klasę i nazwę metody z listy rozwijanej. Aby odwołać się do metod, typów i funkcji w zapytaniu usługi Stream Analytics, klasy muszą być zdefiniowane jako publiczne , a obiekty muszą być zdefiniowane jako statyczne publiczne.

    Konfiguracja funkcji ostrej w języku C usługi Stream Analytics w programie VS Code

    Jeśli chcesz użyć funkcji zdefiniowanej przez użytkownika języka C# z biblioteki DLL, wybierz pozycję Wybierz ścieżkę biblioteki dll , aby wybrać bibliotekę DLL. Następnie wybierz pozycję Wybierz klasę i Wybierz metodę , aby wybrać powiązaną klasę i nazwę metody z listy rozwijanej.

    Konfiguracja funkcji Sharp w usłudze Stream Analytics C

  4. Wywołaj funkcję zdefiniowanej przez użytkownika w zapytaniu usługi Azure Stream Analytics.

     SELECT price, udf.SquareFunction(price)
 INTO Output
 FROM Input

  5. Przed przesłaniem zadania na platformę Azure skonfiguruj ścieżkę pakietu w pliku konfiguracji zadania , JobConfig.jsonsekcji CustomCodeStorage . Użyj pozycji Wybierz z subskrypcji w funkcji CodeLens, aby wybrać subskrypcję, a następnie wybierz konto magazynu i nazwę kontenera z listy rozwijanej. Pozostaw wartość domyślną Ścieżka. Ten krok nie jest wymagany do testowania lokalnego.

    Wybieranie ścieżki biblioteki

Tworzenie funkcji zdefiniowanej przez użytkownika w programie Visual Studio

Istnieją trzy sposoby implementowania funkcji zdefiniowanych przez użytkownika w narzędziach programu Visual Studio.

  • Pliki CodeBehind w projekcie ASA
  • Funkcje zdefiniowane przez użytkownika z projektu lokalnego
  • Istniejący pakiet z konta usługi Azure Storage

KodBehind

Funkcje zdefiniowane przez użytkownika można napisać w pliku Script.asql CodeBehind. Narzędzia programu Visual Studio automatycznie skompilują plik CodeBehind do pliku zestawu. Zestawy są pakowane jako plik zip i przekazywane do konta magazynu podczas przesyłania zadania na platformę Azure. Aby dowiedzieć się, jak napisać funkcję zdefiniowanej przez użytkownika w języku C# przy użyciu funkcji CodeBehind, wykonaj czynności opisane w samouczku dotyczącym funkcji zdefiniowanej przez użytkownika języka C# dla zadań usługi Stream Analytics Edge .

Projekt lokalny

Aby odwołać się do projektu lokalnego w programie Visual Studio:

  1. Tworzenie nowej standardowej biblioteki klas platformy .NET w rozwiązaniu
  2. Napisz kod w klasie. Należy pamiętać, że klasy muszą być zdefiniowane jako publiczne , a obiekty muszą być zdefiniowane jako statyczne publiczne.
  3. Skompilowanie projektu. Narzędzia spakują wszystkie artefakty w folderze bin do pliku zip i przekażą plik zip do konta magazynu. W przypadku odwołań zewnętrznych użyj odwołania do zestawu zamiast pakietu NuGet.
  4. Odwołaj się do nowej klasy w projekcie usługi Azure Stream Analytics.
  5. Dodaj nową funkcję w projekcie usługi Azure Stream Analytics.
  6. Skonfiguruj ścieżkę zestawu w pliku konfiguracji zadania . JobConfig.json Ustaw ścieżkę zestawu na wartość Odwołanie do projektu lokalnego lub CodeBehind.
  7. Ponownie skompiluj zarówno projekt funkcji, jak i projekt usługi Azure Stream Analytics.

Przykład

W tym przykładzie UDFTest jest projektem biblioteki klas C#, a ASAUDFDemo jest projektem usługi Azure Stream Analytics, który będzie odwoływać się do narzędzia UDFTest.

Projekt usługi Azure Stream Analytics IoT Edge w programie Visual Studio

  1. Skompiluj projekt języka C#, który umożliwi dodanie odwołania do funkcji zdefiniowanej przez użytkownika języka C# z zapytania usługi Azure Stream Analytics.

    Tworzenie projektu usługi Azure Stream Analytics IoT Edge w programie Visual Studio

  2. Dodaj odwołanie do projektu C# w projekcie ASA. Kliknij prawym przyciskiem myszy węzeł Odwołania i wybierz polecenie Dodaj odwołanie.

    Dodawanie odwołania do projektu C# w programie Visual Studio

  3. Wybierz z listy nazwę projektu języka C#.

    Wybierz nazwę projektu w języku C# z listy referencyjnej

  4. W obszarze Odwołania w Eksplorator rozwiązań powinny zostać wyświetlone testy UDF.

    Wyświetlanie dokumentacji funkcji zdefiniowanej przez użytkownika w Eksploratorze rozwiązań

  5. Kliknij prawym przyciskiem myszy folder Funkcje i wybierz pozycję Nowy element.

    Dodawanie nowego elementu do usługi Functions w rozwiązaniu Azure Stream Analytics Edge

  6. Dodaj funkcję języka C# SquareFunction.json do projektu usługi Azure Stream Analytics.

    Wybieranie funkcji CSharp z elementów usługi Stream Analytics Edge w programie Visual Studio

  7. Kliknij dwukrotnie funkcję w Eksplorator rozwiązań, aby otworzyć okno dialogowe konfiguracji.

    Konfiguracja funkcji ostrej języka C w programie Visual Studio

  8. W konfiguracji funkcji języka C# wybierz pozycję Załaduj z listy rozwijanej Odwołanie do projektu usługi ASA oraz powiązane nazwy zestawów, klas i metod. Aby odwołać się do metod, typów i funkcji w zapytaniu usługi Stream Analytics, klasy muszą być zdefiniowane jako publiczne , a obiekty muszą być zdefiniowane jako statyczne publiczne.

    Konfiguracja funkcji ostrej w języku C usługi Stream Analytics w programie Visual Studio

Istniejące pakiety

Możesz tworzyć funkcje UDF platformy .NET Standard w dowolnym wybranym środowisku IDE i wywoływać je z zapytania usługi Azure Stream Analytics. Najpierw skompiluj kod i spakuj wszystkie biblioteki DLL. Format pakietu ma ścieżkę /UserCustomCode/CLR/*. Następnie przekaż UserCustomCode.zip do katalogu głównego kontenera na koncie usługi Azure Storage.

Po przekazaniu pakietów zip zestawu do konta usługi Azure Storage możesz użyć funkcji w zapytaniach usługi Azure Stream Analytics. Wystarczy uwzględnić informacje o magazynie w konfiguracji zadania usługi Stream Analytics. Nie można przetestować funkcji lokalnie przy użyciu tej opcji, ponieważ narzędzia programu Visual Studio nie będą pobierać pakietu. Ścieżka pakietu jest analizowana bezpośrednio do usługi.

Aby skonfigurować ścieżkę zestawu w pliku konfiguracji zadania, JobConfig.json:

Rozwiń sekcję Konfiguracja kodu skonfigurowana przez użytkownika, a następnie wypełnij konfigurację za pomocą następujących sugerowanych wartości:

Ustawienie Sugerowana wartość
Zasób globalnych ustawień magazynu Wybierz źródło danych z bieżącego konta
Subskrypcja globalnych ustawień magazynu < Twoja subskrypcja >
Globalne konto magazynu ustawień magazynu < twoje konto magazynu >
Zasób niestandardowych ustawień magazynu kodu Wybierz źródło danych z bieżącego konta
Niestandardowe konto magazynu ustawień magazynu kodu < twoje konto magazynu >
Kontener niestandardowych ustawień magazynu kodu < kontener magazynu >
Niestandardowe źródło zestawu kodu Istniejące pakiety zestawów z chmury
Niestandardowe źródło zestawu kodu UserCustomCode.zip

Rejestrowanie użytkowników

Mechanizm rejestrowania umożliwia przechwytywanie informacji niestandardowych podczas wykonywania zadania. Za pomocą danych dziennika można debugować lub oceniać poprawność kodu niestandardowego w czasie rzeczywistym.

Klasa StreamingContext umożliwia publikowanie informacji diagnostycznych przy użyciu StreamingDiagnostics.WriteError funkcji . Poniższy kod przedstawia interfejs udostępniany przez usługę Azure Stream Analytics.

public abstract class StreamingContext
{
    public abstract StreamingDiagnostics Diagnostics { get; }
}

public abstract class StreamingDiagnostics
{
    public abstract void WriteError(string briefMessage, string detailedMessage);
}

StreamingContext parametr jest przekazywany jako parametr wejściowy do metody UDF i może być używany w ramach funkcji zdefiniowanej przez użytkownika do publikowania niestandardowych informacji dziennika. W poniższym MyUdfMethod przykładzie zdefiniowano dane wejściowe, które są dostarczane przez zapytanie, oraz dane wejściowe kontekstu jako StreamingContext, udostępniane przez aparat środowiska uruchomieniowego.

public static long MyUdfMethod(long data, StreamingContext context)
{
    // write log
    context.Diagnostics.WriteError("User Log", "This is a log message");
    
    return data;
}

Wartość StreamingContext nie musi być przekazywana przez zapytanie SQL. Usługa Azure Stream Analytics automatycznie udostępnia obiekt kontekstu, jeśli parametr wejściowy jest obecny. Użycie elementu MyUdfMethod nie zmienia się, jak pokazano w poniższym zapytaniu:

SELECT udf.MyUdfMethod(input.value) as udfValue FROM input

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

Ograniczenia

Wersja zapoznawcza funkcji zdefiniowanej przez użytkownika ma obecnie następujące ograniczenia:

  • Funkcje zdefiniowane przez użytkownika platformy .NET Standard można tworzyć tylko w programie Visual Studio Code lub Visual Studio i publikować je na platformie Azure. Wersje UDF platformy .NET Standard tylko do odczytu można wyświetlić w obszarze Funkcje w Azure Portal. Tworzenie funkcji platformy .NET Standard nie jest obsługiwane w Azure Portal.

  • Edytor zapytań Azure Portal wyświetla błąd podczas korzystania z funkcji zdefiniowanej przez użytkownika platformy .NET Standard w portalu.

  • Wywoływanie zewnętrznych punktów końcowych REST, na przykład wykonywanie wyszukiwania wstecznego adresu IP lub ściąganie danych referencyjnych ze źródła zewnętrznego

  • Ponieważ niestandardowy kod współuzytuje kontekst z aparatem usługi Azure Stream Analytics, kod niestandardowy nie może odwoływać się do niczego, co ma konfliktową przestrzeń nazw/dll_name z kodem usługi Azure Stream Analytics. Na przykład nie można odwołać się do pliku Newtonsoft Json.

  • Pliki pomocnicze zawarte w projekcie są kopiowane do pliku zip kodu niestandardowego użytkownika, który jest używany podczas publikowania zadania w chmurze. Wszystkie pliki w podfolderach są kopiowane bezpośrednio do katalogu głównego folderu Kod niestandardowy użytkownika w chmurze po rozpakowaniu. Zip jest "spłaszczone", gdy dekompresowany.

  • Niestandardowy kod użytkownika nie obsługuje pustych folderów. Nie dodawaj pustych folderów do plików pomocniczych w projekcie.

Następne kroki