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

Artykuł
03/05/2024

Ważne

Funkcje zdefiniowane przez użytkownika platformy .Net Standard dla usługi Azure Stream Analytics zostaną wycofane 30 września 2024 r. Po tej dacie nie będzie można używać tej funkcji. Przejdź do funkcji zdefiniowanych przez użytkownika w języku JavaScript dla usługi Azure Stream Analytics.

Usługa Azure Stream Analytics oferuje język zapytań przypominający sql na potrzeby 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 UDF 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
Wschodnie stany USA
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żywanej do ich zastosowania.

Obsługiwane typy i mapowanie

Aby wartości usługi Azure Stream Analytics były używane w języku C#, muszą być marshalowane 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
liczba zmiennoprzecinkowa	double
Nvarchar(max)	string
datetime	DateTime
Nagraj	Ciąg słownika<, obiekt>
Tablica	Object[]

To samo dotyczy sytuacji, gdy dane muszą być marshalowane 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	liczba zmiennoprzecinkowa
string	Nvarchar(max)
DateTime	Data i godzina
struktura	Nagraj
obiekt	Nagraj
Object[]	Tablica
Ciąg słownika<, obiekt>	Nagraj

Opracowywanie funkcji zdefiniowanej przez użytkownika w programie Visual Studio Code

Narzędzia programu Visual Studio Code dla 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 programu 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:

Utwórz nową bibliotekę klas standardowych platformy .NET na komputerze lokalnym.
Napisz kod w klasie. Należy pamiętać, że klasy muszą być zdefiniowane jako publiczne , a obiekty muszą być zdefiniowane jako statyczne publiczne.
Dodaj nowy plik konfiguracji funkcji CSharp w projekcie usługi Azure Stream Analytics i odwołaj się do projektu biblioteki klas CSharp.
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 zawierających 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.

Azure Stream Analytics project in Visual Studio Code

Następująca funkcja zdefiniowana przez użytkownika ma funkcję, która mnoży liczbę całkowitą samą 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.

Kliknij prawym przyciskiem myszy folder Funkcje i wybierz polecenie Dodaj element.
Dodaj funkcję języka C# SquareFunction do projektu usługi Azure Stream Analytics.
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.

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.
Wywołaj funkcję zdefiniowanej przez użytkownika w zapytaniu usługi Azure Stream Analytics.
```
 SELECT price, udf.SquareFunction(price)
 INTO Output
 FROM Input 
```
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.

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 języka C# przy użyciu funkcji CodeBehind, wykonaj samouczek 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:

Tworzenie nowej standardowej biblioteki klas platformy .NET w rozwiązaniu
Napisz kod w klasie. Należy pamiętać, że klasy muszą być zdefiniowane jako publiczne , a obiekty muszą być zdefiniowane jako statyczne publiczne.
Skompiluj projekt. 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.
Odwołaj się do nowej klasy w projekcie usługi Azure Stream Analytics.
Dodaj nową funkcję w projekcie usługi Azure Stream Analytics.
Skonfiguruj ścieżkę zestawu w pliku konfiguracji zadania . JobConfig.json Ustaw ścieżkę zestawu na wartość Odwołanie do lokalnego projektu lub KodBehind.
Ponownie skompiluj zarówno projekt funkcji, jak i projekt usługi Azure Stream Analytics.

Przykład

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

Azure Stream Analytics IoT Edge project in Visual Studio

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.
Dodaj odwołanie do projektu C# w projekcie ASA. Kliknij prawym przyciskiem myszy węzeł Odwołania i wybierz polecenie Dodaj odwołanie.
Wybierz z listy nazwę projektu języka C#.
W obszarze Odwołania w Eksplorator rozwiązań powinien zostać wyświetlony test UDFTest.
Kliknij prawym przyciskiem myszy folder Funkcje i wybierz pozycję Nowy element.
Dodaj funkcję języka C# SquareFunction.json do projektu usługi Azure Stream Analytics.
Kliknij dwukrotnie funkcję w Eksplorator rozwiązań, aby otworzyć okno dialogowe konfiguracji.
W konfiguracji funkcji języka C# wybierz pozycję Załaduj z listy rozwijanej Dokumentacja projektu 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.

Istniejące pakiety

Możesz utworzyć funkcje zdefiniowane przez użytkownika platformy .NET Standard w dowolnym wybranym środowisku IDE i wywołać je z poziomu 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 element 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 za pomocą 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 Ustawienia magazynu globalnego	Wybierz źródło danych z bieżącego konta
Subskrypcja usługi Storage globalnej Ustawienia	< Twoja subskrypcja >
Globalne konto magazynu Ustawienia magazynu	< konto magazynu >
Zasób Ustawienia magazynu kodu niestandardowego	Wybierz źródło danych z bieżącego konta
Niestandardowe konto magazynu kodu Ustawienia magazynu	< konto magazynu >
Niestandardowy kontener Ustawienia 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 uruchamiania 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 definiuje dane wejściowe, które są dostarczane przez zapytanie, oraz dane wejściowe kontekstu jako StreamingContextelement , 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 zdefiniowane przez użytkownika platformy .NET Standard tylko do odczytu można wyświetlić w obszarze Funkcje w witrynie Azure Portal. Tworzenie funkcji platformy .NET Standard nie jest obsługiwane w witrynie Azure Portal.
Edytor zapytań witryny 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 odwrotnego adresu IP lub ściąganie danych referencyjnych ze źródła zewnętrznego
Ponieważ niestandardowy kontekst udziałów kodu 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.
Kod niestandardowy użytkownika nie obsługuje pustych folderów. Nie dodawaj pustych folderów do plików pomocniczych w projekcie.

Udostępnij za pośrednictwem

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

Regiony

Ścieżka pakietu

Obsługiwane typy i mapowanie

Opracowywanie funkcji zdefiniowanej przez użytkownika w programie Visual Studio Code

Projekt lokalny

Lokalne biblioteki DLL

Przykład

Tworzenie funkcji zdefiniowanej przez użytkownika w programie Visual Studio

KodBehind

Projekt lokalny

Przykład

Istniejące pakiety

Rejestrowanie użytkowników

Ograniczenia

Następne kroki

Opinia

Dodatkowe zasoby