.NET Standard felhasználó által definiált függvények fejlesztése Azure Stream Analytics-feladatokhoz (előzetes verzió)

Fontos

2024. szeptember 30-án megszűnnek az Azure Stream Analytics .Net Standard által definiált felhasználói függvények. Ezt követően a funkció nem használható. Váltsa át a JavaScript felhasználó által definiált függvényekre az Azure Stream Analyticshez.

Az Azure Stream Analytics egy SQL-hez hasonló lekérdezési nyelvet kínál az eseményadatok streamjeinek átalakításához és számításokhoz. Számos beépített függvény létezik, de egyes összetett forgatókönyvek további rugalmasságot igényelnek. A .NET Standard felhasználó által definiált függvényekkel (UDF) a Stream Analytics lekérdezési nyelvének kibővítéséhez meghívhatja saját, bármely .NET-szabványnyelven (C#, F#stb.) írt függvényeit. Az UDF-ek lehetővé teszik összetett matematikai számítások elvégzését, egyéni ML-modellek importálását ML.NET használatával, valamint egyéni számítási logikát a hiányzó adatokhoz. A Stream Analytics-feladatok UDF-funkciója jelenleg előzetes verzióban érhető el, és nem használható éles számítási feladatokban.

Régiók

A .NET felhasználó által definiált függvény funkciója engedélyezve van a Stream Analytics-fürtökön futó felhőalapú feladatokhoz. A Standard több-bérlős SKU-n futó munkafolyamatok a következő nyilvános régiókban használhatják ezt a funkciót:

  • USA nyugati középső régiója
  • Észak-Európa
  • USA keleti régiója
  • USA nyugati régiója
  • USA 2. keleti régiója
  • Nyugat-Európa

Ha bármely más régióban szeretné használni ezt a funkciót, kérheti a hozzáférést.

Csomag elérési útja

Bármely UDF-csomag formátuma rendelkezik az elérési útmal /UserCustomCode/CLR/*. A dinamikus csatolási kódtárak (DLL-ek) és az erőforrások a mappába vannak másolva, ami segít elkülöníteni a felhasználói DLL-eket a rendszertől és az /UserCustomCode/CLR/* Azure Stream Analytics DLL-ektől. Ez a csomagútvonal az alkalmazásukhoz használt módszertől függetlenül minden függvényhez használható.

Támogatott típusok és leképezés

Ahhoz, hogy az Azure Stream Analytics-értékeket c#-ban lehessen használni, azokat az egyik környezetből a másikba kell helyezni. A marshaling az UDF összes bemeneti paraméteréhez történik. Minden Azure Stream Analytics-típushoz tartozik egy megfelelő C# típus az alábbi táblázatban:

Azure Stream Analytics-típus C# típus
bigint hosszú
float dupla
nvarchar(max) karakterlánc
datetime Dátum/idő
Rekord Szótár<karakterlánc, objektum>
Tömb Objektum[]

Ugyanez igaz, ha az adatokat C#-ból az Azure Stream Analyticsbe kell továbbítani, ami egy UDF kimeneti értékén történik. Az alábbi táblázat a támogatott típusokat mutatja be:

C# típus Azure Stream Analytics-típus
hosszú bigint
dupla float
karakterlánc nvarchar(max)
Dátum/idő dátumIdő
struktúra Rekord
objektum Rekord
Objektum[] Tömb
Szótár<string, objektum> Rekord

UDF fejlesztése a Visual Studio Code-ban

Az Azure Stream AnalyticsHez készült Visual Studio Code-eszközök megkönnyítik az UDF-ek írását, a feladatok helyi (akár offline) tesztelését, valamint a Stream Analytics-feladat Azure-ban való közzétételét.

A Visual Studio Code-eszközökben kétféleképpen implementálhatja a .NET szabványú UDF-eket.

  • UDF helyi DLL-ekből
  • UDF helyi projektből

Helyi projekt

A felhasználó által definiált függvények olyan szerelvényben írhatók, amelyekre később egy Azure Stream Analytics-lekérdezés hivatkozik. Ez az ajánlott lehetőség olyan összetett függvényekhez, amelyek a .NET Standard nyelv teljes erejét igénylik a kifejezési nyelven túl, például eljárási logikát vagy rekurziót. A helyi projektből származó UDF-ek akkor is használhatók, ha több Azure Stream Analytics-lekérdezésben meg kell osztania a függvénylogikát. Az UDF-ek helyi projekthez való hozzáadása lehetővé teszi a függvények helyi hibakeresését és tesztelését.

Helyi projektre való hivatkozás:

  1. Hozzon létre egy új .NET standard osztálytárat a helyi gépen.
  2. Írja meg a kódot az osztályában. Ne feledje, hogy az osztályokat nyilvánosként kell definiálni, az objektumokat pedig statikus nyilvánosként kell definiálni.
  3. Adjon hozzá egy új CSharp-függvénykonfigurációs fájlt az Azure Stream Analytics-projektben, és hivatkozzon a CSharp osztálytárprojektre.
  4. Konfigurálja a szerelvény elérési útját a feladatkonfigurációs fájl JobConfig.jsonCustomCodeStorage szakaszában. Erre a lépésre nincs szükség a helyi teszteléshez.

Helyi DLL-ek

A felhasználó által definiált függvényeket tartalmazó helyi DLL-címekre is hivatkozhat.

Example

Ebben a példában a CSharpUDFProject egy C# osztálykódtár-projekt, az ASAUDFDemo pedig az Azure Stream Analytics-projekt, amely a CSharpUDFProjectre hivatkozik.

Azure Stream Analytics-projekt a Visual Studio Code-ban

Az alábbi UDF függvény önmagában megszorozza az egész számot, hogy az egész szám négyzetét hozza létre. Az osztályokat nyilvánosként kell definiálni, az objektumokat pedig statikus nyilvánosként kell definiálni.

using System;

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

Az alábbi lépések bemutatják, hogyan adhat hozzá C# UDF-függvényt a Stream Analytics-projekthez.

  1. Kattintson a jobb gombbal a Functions mappára, és válassza az Elem hozzáadása lehetőséget.

    Új függvény hozzáadása az Azure Stream Analytics-projektben

  2. Adjon hozzá egy C# -függvényt, a SquareFunctiont az Azure Stream Analytics-projekthez.

    A CSharp függvény kiválasztása Stream Analytics-projektből a VS Code-ban

    Adja meg a CSharp függvény nevét a VS Code-ban

  3. A C#-függvény konfigurációjában válassza a Kódtár projektútvonalának kiválasztása lehetőséget a C# projekt kiválasztásához a legördülő listából, majd válassza a Projekt létrehozása lehetőséget a projekt létrehozásához. Ezután válassza a Select class and Select metódus lehetőséget a kapcsolódó osztály és metódus nevének kiválasztásához a legördülő listából. A Stream Analytics-lekérdezés metódusaira, típusaira és függvényeire való hivatkozáshoz az osztályokat nyilvánosként kell definiálni, az objektumokat pedig statikus nyilvánosként kell definiálni.

    Stream Analytics C éles függvénykonfiguráció VS Code

    Ha egy DLL-ből szeretné használni a C# UDF-et, válassza az Erőforrástár dll-elérési útjának kiválasztása lehetőséget a DLL kiválasztásához. Ezután válassza a Select class and Select metódus lehetőséget a kapcsolódó osztály és metódus nevének kiválasztásához a legördülő listából.

    Stream Analytics C éles függvénykonfiguráció

  4. Az UDF meghívása az Azure Stream Analytics-lekérdezésben.

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

  5. Mielőtt elküldené a feladatot az Azure-ba, konfigurálja a csomag elérési útját a feladat konfigurációs fájljában, JobConfig.jsona CustomCodeStorage szakaszban. Használja a Választás az előfizetések közül opciót a CodeLensben, hogy kiválassza az előfizetését, és válassza ki a tárfiókot és a tároló nevét a legördülő listából. Hagyja meg az elérési utat alapértelmezettként. Erre a lépésre nincs szükség a helyi teszteléshez.

    Tár elérési útjának kiválasztása

UDF fejlesztése a Visual Studióban

Az UDF-eket háromféleképpen implementálhatja a Visual Studio-eszközökben.

  • A CodeBehind-fájlok az ASA-projektben
  • UDF helyi projektből
  • Meglévő csomag Egy Azure Storage-fiókból

CodeBehind

Felhasználó által definiált függvényeket a Script.asql CodeBehindben írhat. A Visual Studio-eszközök automatikusan összeállítják a CodeBehind-fájlt egy szerelvényfájlba. A szerelvények zip-fájlként vannak csomagolva, és feltöltésre kerülnek a tárolófiókjába, amikor beküldi a feladatot az Azure szolgáltatásba. A C# UDF a CodeBehind használatával történő írását a Stream Analytics Edge-feladatokhoz készült C# UDF oktatóanyagának követésével ismerheti meg.

Helyi projekt

Helyi projektre való hivatkozás a Visual Studióban:

  1. Új .NET standard osztálykódtár létrehozása a megoldásban
  2. Írja meg a kódot az osztályában. Ne feledje, hogy az osztályokat nyilvánosként kell definiálni, az objektumokat pedig statikus nyilvánosként kell definiálni.
  3. Hozza létre a projektet. Az eszközök a bin mappában lévő összes összetevőt zip-fájlba csomagolják, és feltöltik a zip-fájlt a tárfiókba. Külső hivatkozások esetén a NuGet-csomag helyett szerelvényhivatkozást használjon.
  4. Hivatkozzon az Azure Stream Analytics-projekt új osztályára.
  5. Adjon hozzá egy új függvényt az Azure Stream Analytics-projekthez.
  6. Állítsa be az assembly elérési útját a feladatkonfigurációs fájlban. JobConfig.json Állítsa az összeállítás elérési útját helyi projekthivatkozásra vagy CodeBehind.
  7. A függvényprojekt és az Azure Stream Analytics-projekt újraépítése.

Example

Ebben a példában az UDFTest egy C# osztálykódtárprojekt, az ASAUDFDemo pedig az Azure Stream Analytics-projekt, amely az UDFTestre hivatkozik.

Azure Stream Analytics IoT Edge-projekt a Visual Studióban

  1. Hozza létre a C#-projektet, amely lehetővé teszi, hogy az Azure Stream Analytics-lekérdezésből hivatkozásokat adjon a C# UDF-hez.

    Azure Stream Analytics IoT Edge-projekt létrehozása a Visual Studióban

  2. Adja hozzá a C#-projektre mutató hivatkozást az ASA-projektben. Kattintson a jobb gombbal a Hivatkozások csomópontra, és válassza a Hivatkozás hozzáadása parancsot.

    Hivatkozás hozzáadása C#-projekthez a Visual Studióban

  3. Válassza ki a C#-projekt nevét a listából.

    A C#-projekt nevének kiválasztása a referencialistából

  4. A MegoldáskezelőHivatkozásai területén az UDFTestnek szerepelnie kell.

    A felhasználó által definiált függvényhivatkozás megtekintése a Megoldáskezelőben

  5. Kattintson a jobb gombbal a Functions mappára, és válassza az Új elem lehetőséget.

    Új elem hozzáadása a Functionshöz az Azure Stream Analytics Edge-megoldásban

  6. Adjon hozzá egy C# -függvénytSquareFunction.json az Azure Stream Analytics-projekthez.

    A CSharp függvény kiválasztása Stream Analytics Edge-elemekből a Visual Studióban

  7. Kattintson duplán a függvényre a Megoldáskezelőben a konfigurációs párbeszédpanel megnyitásához.

    C éles függvénykonfiguráció a Visual Studióban

  8. A C#-függvény konfigurációjában válassza a Betöltés lehetőséget az ASA-projektreferenciából , valamint a kapcsolódó szerelvény-, osztály- és metódusneveket a legördülő listából. A Stream Analytics-lekérdezés metódusaira, típusaira és függvényeire való hivatkozáshoz az osztályokat nyilvánosként kell definiálni, az objektumokat pedig statikus nyilvánosként kell definiálni.

    Stream Analytics C# függvény konfiguráció Visual Studio

Meglévő csomagok

A .NET Standard UDF-eket tetszőleges IDE-ben létrehozhatja, és meghívhatja őket az Azure Stream Analytics-lekérdezésből. Először fordítsa le a kódot, és csomagolja be az összes DLL-t. A csomag formátuma /UserCustomCode/CLR/* elérési úttal rendelkezik. Ezután töltse fel a UserCustomCode.zip fájlt az Azure Storage-fiókja tárolójának gyökerébe.

Miután feltöltötte a szerelvény zip-csomagjait az Azure Storage-fiókjába, használhatja a függvényeket az Azure Stream Analytics-lekérdezésekben. Mindössze annyit kell tennie, hogy vegye fel a tárolási adatokat a Stream Analytics-feladat konfigurációjában. Ezzel a beállítással nem tesztelheti helyileg a függvényt, mert a Visual Studio eszközei nem töltik le a csomagot. A csomag elérési útját közvetlenül a szolgáltatásnak adjuk át elemzésre.

A feladatkonfigurációs fájl JobConfig.jsonszerelvényútvonalának konfigurálásához:

Bontsa ki a User-Defined Kódkonfiguráció szakaszt, és töltse ki a konfigurációt a következő javasolt értékekkel:

Beállítás Javasolt érték
Globális tárolási beállítások erőforrása Adatforrás kiválasztása az aktuális fiókból
Globális tárolási beállítások előfizetése < előfizetése >
Globális tárfiók beállítások < a tárfiók >
Egyéni kódtár-beállítások erőforrása Adatforrás kiválasztása az aktuális fiókból
Egyéni kódtár-beállítások tárfiókja < a tárfiók >
Egyéni kódtár-beállítások tárolója < a tárolókonténer >
Egyéni kódszerelvény forrása Meglévő szerelvénycsomagok a felhőből
Egyéni kódszerelvény forrása UserCustomCode.zip

Felhasználói naplózás

A naplózási mechanizmus lehetővé teszi egyéni adatok rögzítését egy feladat futtatása közben. Naplóadatokkal valós időben hibakeresést vagy az egyéni kód helyességének felmérését végezheti el.

Az StreamingContext osztály lehetővé teszi a diagnosztikai adatok közzétételét a StreamingDiagnostics.WriteError függvény használatával. Az alábbi kód az Azure Stream Analytics által közzétett felületet mutatja.

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

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

StreamingContext a rendszer bemeneti paraméterként továbbítja az UDF-metódusnak, és az UDF-ben az egyéni naplóadatok közzétételére használható. Az alábbi példában a MyUdfMethod lekérdezés biztosít egy adatbemenetet, és a futási környezet motorja biztosít egy környezeti bemenetet StreamingContext.

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

Az StreamingContext sql-lekérdezésnek nem kell átadnia az értéket. Az Azure Stream Analytics automatikusan biztosít egy környezeti objektumot, ha van bemeneti paraméter. A MyUdfMethod használata nem változik, ahogyan az a következő lekérdezésben látható:

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

A naplóüzeneteket a diagnosztikai naplókon keresztül érheti el.

Korlátozások

Az UDF előzetes verziója jelenleg a következő korlátozásokkal rendelkezik:

  • A .NET Standard UDF-ek csak a Visual Studio Code-ban vagy a Visual Studióban hozhatók össze, és közzétehetők az Azure-ban. A .NET Standard UDF-ek írásvédett verziói az Azure Portal Függvények területén tekinthetők meg. A .NET Standard függvények létrehozása nem támogatott az Azure Portalon.

  • Az Azure Portal lekérdezésszerkesztője hibát jelenít meg a .NET Standard UDF portálon való használatakor.

  • Külső REST-végpontok meghívása, például fordított IP-keresés vagy referenciaadatok lekérése külső forrásból

  • Mivel az egyéni kód az Azure Stream Analytics-motorral osztja meg a környezetet, az egyéni kód nem hivatkozhat semmire, amely ütköző névtérrel/dll_name rendelkezik az Azure Stream Analytics-kóddal. Nem hivatkozhat például a Newtonsoft Jsonra.

  • A projektben szereplő támogató fájlok a felhasználói egyéni kód zip-fájljába lesznek másolva, amelyet a feladat felhőben való közzétételekor használnak. Az almappákban lévő összes fájl közvetlenül a felhőben található Felhasználói Egyéni Kód mappa gyökerébe lesz másolva, miután kibontottuk. A zip "kibontásra kerül" kicsomagoláskor.

  • A felhasználói egyéni kód nem támogatja az üres mappákat. Ne adjon hozzá üres mappákat a projekt támogató fájljaihoz.

Következő lépések

  • Last updated on