Vývoj uživatelem definovaných funkcí .NET Standard pro úlohy Azure Stream Analytics (Preview)

Důležité

30. září 2024 se vyřadí uživatelem definované funkce .Net Standard pro Azure Stream Analytics. Po tomto datu nebude možné tuto funkci používat. Přejděte na uživatelem definované funkce JavaScriptu pro Azure Stream Analytics.

Azure Stream Analytics nabízí dotazovací jazyk podobný JAZYKu SQL pro provádění transformací a výpočtů v datových proudech událostí. Existuje mnoho předdefinovaných funkcí, ale některé složité scénáře vyžadují větší flexibilitu. Pomocí uživatelem definovaných funkcí .NET Standard (UDF) můžete vyvolat vlastní funkce napsané v libovolném jazyce .NET Standard (C#, F# atd.) a rozšířit tak dotazovací jazyk Stream Analytics. Funkce UDF umožňují provádět složité matematické výpočty, importovat vlastní modely ML s využitím ML.NET a používat vlastní logiku imputace pro chybějící data. UDF funkce pro práce Stream Analytics je aktuálně v náhledové verzi a neměla by se používat pro produkční pracovní zátěže.

Regions

Funkce uživatelem definované funkce .NET je zapnutá pro cloudové úlohy, které běží v clusterech Stream Analytics. Úlohy, které běží na Standard SKU s více nájemci, můžou tuto funkci využít v následujících veřejných regionech:

• Středozápadní USA
• Severní Evropa
• USA – východ​
• USA – západ
• USA – východ 2
• Západní Evropa

Pokud vás zajímá použití této funkce v jakékoli jiné oblasti, můžete požádat o přístup.

Cesta k balíčku

Formát libovolného balíčku UDF má cestu /UserCustomCode/CLR/*. Dynamické knihovny odkazů (DLL) a prostředky se zkopírují do /UserCustomCode/CLR/* složky, což pomáhá izolovat knihovny DLL uživatelů od systémů a knihoven DLL služby Azure Stream Analytics. Tato cesta balíčku se používá pro všechny funkce bez ohledu na metodu použitou k jejich použití.

Podporované typy a mapování

Aby se hodnoty Azure Stream Analytics používaly v jazyce C#, je potřeba je zařazovat z jednoho prostředí do druhého. Zařazování probíhá pro všechny vstupní parametry UDF. Každý typ Azure Stream Analytics má odpovídající typ v jazyce C# zobrazený v následující tabulce:

Typ Azure Stream Analytics	Typ jazyka C#
bigint	long
float	dvojitý
nvarchar(max)	řetězec
datetime	DateTime
Záznam	Slovník<string, object>
Array	Objekt[]

Totéž platí v případě, že je potřeba data přenášet z C# do Azure Stream Analytics, což se děje s výstupní hodnotou uživatelsky definované funkce. Následující tabulka ukazuje, jaké typy jsou podporované:

Typ jazyka C#	Typ Azure Stream Analytics
long	bigint
dvojitý	float
řetězec	nvarchar(max)
DateTime	datum a čas
struktura	Záznam
objekt	Záznam
Objekt[]	Array
Slovník<string, object>	Záznam

Vývoj uživatelsky definované funkce v editoru Visual Studio Code

Nástroje Visual Studio Code pro Azure Stream Analytics usnadňují psaní UDFs (funkcí definovaných uživatelem), místní testování úloh (i offline) a publikování úlohy Stream Analytics na Azure.

Existují dva způsoby implementace funkcí definovaných uživatelem ve standardu .NET v nástrojích editoru Visual Studio Code.

• UDF z místních knihoven DLL
• UDF z místního projektu

Místní projekt

Uživatelem definované funkce lze zapsat do sestavení, na které se později odkazuje v dotazu Azure Stream Analytics. Toto je doporučená možnost pro komplexní funkce, které vyžadují plný výkon jazyka .NET Standard nad rámec jazyka výrazů, jako je procedurální logika nebo rekurze. Funkce definované uživatelem (UDFs) z místního projektu se můžou také použít, když potřebujete sdílet logiku funkce v několika dotazech služby Azure Stream Analytics. Přidáním UDF do místního projektu získáte možnost odlaďovat a testovat funkce místně.

Odkaz na místní projekt:

1. Na místním počítači vytvořte novou knihovnu tříd .NET Standard.
2. Napište kód ve třídě. Nezapomeňte, že třídy musí být definovány jako veřejné a objekty musí být definovány jako statické veřejné.
3. Přidejte do projektu Azure Stream Analytics nový konfigurační soubor funkce CSharp a odkazujte na projekt knihovny tříd CSharp.
4. Nakonfigurujte cestu sestavení v konfiguračním souboru úlohy, v JobConfig.jsončásti CustomCodeStorage . Tento krok není nutný pro místní testování.

Místní knihovny DLL

Můžete také odkazovat na místní knihovny DLL, které obsahují uživatelem definované funkce.

Example

V tomto příkladu je CSharpUDFProject projekt knihovny tříd C# a ASAUDFDemo je projekt Azure Stream Analytics, který bude odkazovat na projekt CSharpUDFProject.

Následující UDF (uživatelsky definovaná funkce) má funkci, která vynásobí celé číslo samo sebou, aby se získala druhá mocnina tohoto celého čísla. Třídy musí být definovány jako veřejné a objekty musí být definovány jako statické veřejné.

using System;

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

Následující kroky ukazují, jak do projektu Stream Analytics přidat funkci UDF jazyka C#.

1. Klikněte pravým tlačítkem na složku Functions a zvolte Přidat položku.

   

2. Přidejte funkci C# SquareFunction do projektu Azure Stream Analytics.

   

   

3. V konfiguraci funkce jazyka C# vyberte v rozevíracím seznamu možnost Zvolit cestu projektu knihovny , vyberte projekt jazyka C# a výběrem možnosti Sestavit projekt sestavte projekt. Pak v rozevíracím seznamu zvolte Vybrat třídu a vybrat metodu . Aby bylo možné odkazovat na metody, typy a funkce v dotazu Stream Analytics, musí být třídy definovány jako veřejné a objekty musí být definovány jako statické veřejné.

   

   Pokud chcete použít UDF jazyka C# z knihovny DLL, vyberte Zvolit cestu knihovny dll a zvolte knihovnu DLL. Pak z rozevíracího seznamu zvolte Vybrat třídu a Vybrat metodu pro výběr související třídy a názvu metody.

   

4. V dotazu Azure Stream Analytics vyvolejte UDF.

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

5. Před odesláním úlohy do Azure nakonfigurujte cestu balíčku v konfiguračním souboru úlohy, JobConfig.jsonv části CustomCodeStorage . Pomocí možnosti Vybrat z předplatného v CodeLens zvolte své předplatné a v rozevíracím seznamu zvolte účet úložiště a název kontejneru. Nechejte cestu jako výchozí. Tento krok není nutný pro místní testování.

   

Vytvářejte UDF ve Visual Studio

V nástrojích sady Visual Studio existují tři způsoby implementace uživatelsky definovaných funkcí.

• Soubory CodeBehind v projektu ASA
• UDF z místního projektu
• Existující balíček z účtu úložiště Azure

CodeBehind

Uživatelem definované funkce můžete psát v Script.asql CodeBehind. Nástroje sady Visual Studio automaticky kompilují soubor CodeBehind do souboru sestavení. Sestavení jsou zabalena jako soubor ZIP a při odeslání úlohy do Azure jsou následně nahrána do vašeho úložiště. Dozvíte se, jak psát UDF jazyka C# pomocí CodeBehindu, pokud budete postupovat podle tutoriálu UDF jazyka C# pro úlohy Stream Analytics Edge.

Místní projekt

Odkaz na místní projekt v sadě Visual Studio:

1. Vytvoření nové knihovny tříd .NET Standard ve vašem řešení
2. Napište kód ve třídě. Nezapomeňte, že třídy musí být definovány jako veřejné a objekty musí být definovány jako statické veřejné.
3. Sestavte svůj projekt. Nástroje zabalí všechny artefakty ve složce bin do souboru ZIP a nahrají soubor ZIP do účtu úložiště. Pro externí odkazy použijte odkaz na sestavení místo balíčku NuGet.
4. Zařaďte novou třídu do projektu Azure Stream Analytics.
5. Přidejte do projektu Azure Stream Analytics novou funkci.
6. Nakonfigurujte cestu sestavení v konfiguračním souboru úlohy JobConfig.json. Nastavte cestu sestavení na odkaz na místní projekt nebo CodeBehind.
7. Znovu sestavte projekt funkce i projekt Azure Stream Analytics.

Example

V tomto příkladu je UDFTest projekt knihovny tříd C# a ASAUDFDemo je projekt Azure Stream Analytics, který bude odkazovat na UDFTest.

1. Sestavte projekt jazyka C#, který vám umožní přidat odkaz na UDF jazyka C# z dotazu Azure Stream Analytics.

   

2. Přidejte odkaz na projekt C# v projektu ASA. Klikněte pravým tlačítkem myši na uzel Odkazy a zvolte Přidat odkaz.

   

3. V seznamu zvolte název projektu C#.

   

4. V Průzkumníku řešení by se měl zobrazit UDFTest uvedený v části Odkazy.

   

5. Klikněte pravým tlačítkem na složku Functions a zvolte Nová položka.

   

6. Přidejte funkci jazyka C# SquareFunction.json do svého projektu Azure Stream Analytics.

   

7. Poklikáním na funkci v Průzkumníku řešení otevřete dialogové okno konfigurace.

   

8. V konfiguraci funkce jazyka C# zvolte Načíst z odkazu na projekt ASA a související sestavení, třídu a názvy metod z rozevíracího seznamu. Aby bylo možné odkazovat na metody, typy a funkce v dotazu Stream Analytics, musí být třídy definovány jako veřejné a objekty musí být definovány jako statické veřejné.

   

Existující balíčky

Můžete vytvářet UDFs v .NET Standard v libovolném integrovaném vývojovém prostředí dle vašeho výběru a volat je z dotazu Azure Stream Analytics. Nejprve zkompilujte kód a zabalte všechny knihovny DLL. Formát balíčku má cestu /UserCustomCode/CLR/*. Pak nahrajte UserCustomCode.zip do kořenového adresáře kontejneru v účtu úložiště Azure.

Jakmile se balíčky ZIP sestavení nahrají do účtu úložiště Azure, můžete použít funkce v dotazech Azure Stream Analytics. Stačí, když do konfigurace úlohy Stream Analytics zahrnete informace o úložišti. Funkci nemůžete otestovat místně pomocí této možnosti, protože nástroje sady Visual Studio nebudou stahovat váš balíček. Cesta k balíčku je službou přímo analyzována.

Chcete-li konfigurovat cestu sestavení v konfiguračním souboru úlohy, JobConfig.json:

Rozbalte oddíl Konfigurace uživatelsky definovaného kódu a vyplňte konfiguraci následujícími navrhovanými hodnotami:

Nastavení	Navrhovaná hodnota
Prostředek globálního nastavení úložiště	Volba zdroje dat z aktuálního účtu
Předplatné globálního nastavení úložiště	< vaše předplatné >
Globální nastavení úložiště Účet úložiště	< váš účet pro úložiště >
Prostředek vlastního nastavení úložiště kódu	Volba zdroje dat z aktuálního účtu
Nastavení úložiště vlastního kódu Účet úložiště	< váš účet pro úložiště >
Kontejner nastavení úložiště vlastního kódu	< váš kontejner úložiště >
Zdroj sestavení vlastního kódu	Existující balíčky sestavení z cloudu
Zdroj sestavení vlastního kódu	UserCustomCode.zip

Zaznamenávání uživatelských akcí

Mechanismus protokolování umožňuje zachytit vlastní informace, když úloha běží. Data protokolu můžete použít k ladění nebo vyhodnocení správnosti vlastního kódu v reálném čase.

Třída StreamingContext umožňuje publikovat diagnostické informace pomocí StreamingDiagnostics.WriteError funkce. Následující kód ukazuje rozhraní vystavené službou 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 je jako vstupní parametr předáván metodě UDF a lze jej použít v rámci UDF k publikování vlastních informací o protokolu. V následujícím MyUdfMethod příkladu definuje vstup dat, který poskytuje dotaz, a kontextový vstup jako StreamingContext, poskytovaný modulem runtime.

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

Hodnota StreamingContext nemusí být předána dotazem SQL. Azure Stream Analytics poskytuje kontextový objekt automaticky, pokud je k dispozici vstupní parametr. Použití MyUdfMethod se nezmění, jak je znázorněno v následujícím dotazu:

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

Ke zprávám protokolu můžete přistupovat prostřednictvím diagnostických protokolů.

Omezení

UDF Ve verzi Preview aktuálně platí následující omezení:

• UDF .NET Standard lze psát pouze ve Visual Studio Code nebo Visual Studio a publikovat do Azure. Verze uživatelských funkcí .NET Standard jen pro čtení jsou možné zobrazit v části Funkce v Azure portálu. Vytváření funkcí .NET Standard se na webu Azure Portal nepodporuje.

• Editor dotazů na webu Azure Portal zobrazuje chybu při použití UDF .NET Standard na portálu.

• Využití externích koncových bodů REST, například vyhledávání reverzních IP adres nebo přenos referenčních dat z externího zdroje

• Vzhledem k tomu, že vlastní kód sdílí kontext s modulem Azure Stream Analytics, vlastní kód nemůže odkazovat na nic, co má konfliktní obor názvů nebo dll_name s kódem Azure Stream Analytics. Nemůžete například odkazovat na Newtonsoft Json.

• Podpůrné soubory zahrnuté v projektu se zkopírují do souboru ZIP vlastního kódu uživatele, který se používá při publikování úlohy do cloudu. Při rozbalení se všechny soubory v podsložkách zkopírují přímo do kořenové složky uživatelského vlastního kódu v cloudu. Zip je při dekompresi "zploštěný".

• Vlastní kód uživatele nepodporuje prázdné složky. Nepřidávejte do podpůrných souborů v projektu prázdné složky.

Další kroky

• Kurz: Zápis uživatelem definované funkce jazyka C# pro úlohu Azure Stream Analytics (Preview)
• Kurz: Uživatelem definované funkce Jazyka JavaScript v Azure Stream Analytics
• Vytvoření úlohy Azure Stream Analytics v editoru Visual Studio Code