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

  • Článek

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 definované uživatelem umožňují provádět složité matematické výpočty, importovat vlastní modely ML pomocí ML.NET a používat vlastní logiku imputace pro chybějící data. Funkce definovaná uživatelem pro úlohy Stream Analytics je aktuálně ve verzi Preview a neměla by se používat v produkčních úlohách.

Oblasti

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

  • Středozápad 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 (číslo s plovoucí řádovou čárkou) double
Nvarchar(max) string
datetime DateTime
Zaznamenat Řetězec slovníku<, objekt>
Pole Objekt[]

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

Typ jazyka C# Typ Azure Stream Analytics
long bigint
double float (číslo s plovoucí řádovou čárkou)
string Nvarchar(max)
DateTime data a času.
struct Zaznamenat
objekt Zaznamenat
Objekt[] Pole
Řetězec slovníku<, objekt> Zaznamenat

Vývoj uživatelem definovaného uživatelem v editoru Visual Studio Code

Nástroje Editoru Visual Studio Code pro Azure Stream Analytics usnadňují psaní funkcí definovaných uživatelem, místní testování úloh (i offline) a publikování úlohy Stream Analytics do 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 z místního projektu se můžou použít také v případě, že potřebujete sdílet logiku funkce napříč několika dotazy Azure Stream Analytics. Přidáním uživatelem definovaných funkcí do místního projektu získáte možnost ladit 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.

Příklad

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

Azure Stream Analytics project in Visual Studio Code

Následující funkce definovaná uživatelem má funkci, která vynásobí celé číslo sama o sobě, aby se vytvořil čtverec 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.

    Add new function in Azure Stream Analytics project

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

    Select CSharp function from Stream Analytics project in VS Code

    Enter CSharp function name in VS Code

  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é.

    Stream Analytics C sharp function configuration VS Code

    Pokud chcete použít UDF jazyka C# z knihovny DLL, vyberte Zvolit cestu knihovny dll a zvolte knihovnu DLL. Pak v rozevíracím seznamu zvolte Vybrat třídu a vybrat metodu .

    Stream Analytics C sharp function configuration

  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í.

    Choose library path

Vývoj UDF v sadě Visual Studio

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

  • 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í se zabalí jako soubor ZIP a při odeslání úlohy do Azure se nahrají do vašeho účtu úložiště. V kurzu úloh Stream Analytics Edge se dozvíte, jak psát UDF jazyka C# pomocí CodeBehindu.

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. Odkazujte na novou třídu v projektu Azure Stream Analytics.
  5. Přidejte do projektu Azure Stream Analytics novou funkci.
  6. Nakonfigurujte cestu sestavení v konfiguračním souboru JobConfig.jsonúlohy . Nastavte cestu sestavení na odkaz na místní projekt nebo CodeBehind.
  7. Znovu sestavte projekt funkce i projekt Azure Stream Analytics.

Příklad

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

Azure Stream Analytics IoT Edge project in Visual Studio

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

    Build an Azure Stream Analytics IoT Edge project in Visual Studio

  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.

    Add a reference to a C# project in Visual Studio

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

    Choose your C# project name from the reference list

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

    View the user defined function reference in solution explorer

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

    Add new item to Functions in Azure Stream Analytics Edge solution

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

    Select CSharp function from Stream Analytics Edge items in Visual Studio

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

    C sharp function configuration in Visual Studio

  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é.

    Stream Analytics C sharp function configuration Visual Studio

Existující balíčky

Definované funkce .NET Standard můžete vytvářet v libovolném integrovaném vývojovém prostředí podle 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 se analyzuje přímo do služby.

Konfigurace cesty sestavení v konfiguračním souboru úlohy: JobConfig.json

Rozbalte část Konfigurace kódu definovaného uživatelem a vyplňte do konfigurace následující navrhované hodnoty:

Nastavení Navrhovaná hodnota
Globální prostředek Nastavení úložiště Zvolit zdroj dat z aktuálního účtu
Globální úložiště Nastavení předplatné < vaše předplatné >
Globální účet úložiště Nastavení < váš účet úložiště >
Prostředek Nastavení vlastního úložiště kódu Zvolit zdroj dat z aktuálního účtu
Vlastní úložiště kódu Nastavení účtu úložiště < váš účet úložiště >
Kontejner Nastavení vlastního úložiště kódu < 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

Protokolování uživatelů

Mechanismus protokolování umožňuje zachytit vlastní informace, když je úloha spuštěná. 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 se předává jako vstupní parametr metodě UDF a dá se použít v rámci UDF k publikování vlastních informací protokolu. V následujícím MyUdfMethod příkladu definuje vstup dat, který poskytuje dotaz, a kontextový vstup jako StreamingContextmodul modulu 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í:

  • Uživatelem definované funkce .NET Standard je možné vytvářet pouze v editoru Visual Studio Code nebo v sadě Visual Studio a publikovat je do Azure. Uživatelské funkce .NET Standard jen pro čtení je možné zobrazit v části Funkce na webu Azure Portal. 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.

  • Volání externích koncových bodů REST, například vyhledávání reverzníCH IP adres nebo vyžádání 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