Megosztás a következőn keresztül:

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

  • Cikk

Fontos

Az Azure Stream Analytics felhasználó által definiált .Net Standard-függvényei 2024. szeptember 30-án megszűnnek. 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 termékváltozaton futó feladatok 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 double
nvarchar(max) húr
dátum/idő Dátum/idő
Rögzítés Szótári sztring<, 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
double float
húr nvarchar(max)
Dátum/idő Datetime
Struct Rögzítés
object Rögzítés
Objektum[] Tömb
Szótári sztring<, objektum> Rögzítés

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 be a kódot az osztályba. Ne feledje, hogy az osztályokat nyilvánoskéntkell 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.

Példa

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 project in Visual Studio Code

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.

    Add new function in Azure Stream Analytics project

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

    Select CSharp function from Stream Analytics project in VS Code

    Enter CSharp function name in VS Code

  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éntkell definiálni, az objektumokat pedig statikus nyilvánosként kell definiálni.

    Stream Analytics C sharp function configuration 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 sharp function configuration

  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. Válassza ki előfizetését a CodeLensben az előfizetésből , é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.

    Choose library path

UDF fejlesztése a Visual Studióban

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

  • CodeBehind-fájlok 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ölthetők a tárfiókba, amikor beküldi a feladatot az Azure-ba. 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 be a kódot az osztályba. Ne feledje, hogy az osztályokat nyilvánoskéntkell 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. Konfigurálja a szerelvény elérési útját a feladatkonfigurációs fájlban. JobConfig.json Állítsa a szerelvény elérési útját helyi projekthivatkozásra vagy CodeBehindre.
  7. A függvényprojekt és az Azure Stream Analytics-projekt újraépítése.

Példa

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 project in Visual Studio

  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.

    Build an Azure Stream Analytics IoT Edge project in Visual Studio

  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.

    Add a reference to a C# project in Visual Studio

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

    Choose your C# project name from the reference list

  4. Az UDFTestnek a Hivatkozások területen kell megjelennie a Megoldáskezelő.

    View the user defined function reference in solution explorer

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

    Add new item to Functions in Azure Stream Analytics Edge solution

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

    Select CSharp function from Stream Analytics Edge items in Visual Studio

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

    C sharp function configuration in Visual Studio

  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éntkell definiálni, az objektumokat pedig statikus nyilvánosként kell definiálni.

    Stream Analytics C sharp function configuration 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 az elérési út /UserCustomCode/CLR/*. Ezután töltse fel UserCustomCode.zip a tároló gyökerét az Azure Storage-fiókjában.

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 tartalmazza 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 útja közvetlenül a szolgáltatáshoz lesz elemezve.

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

Bontsa ki a Felhasználói kód konfigurációja szakaszt, és töltse ki a konfigurációt az alábbi javasolt értékekkel:

Beállítás Ajánlott érték
Globális tárolási Gépház erőforrás Choose data source from current account (Adatforrás kiválasztása az aktuális fiókból)
Globális tárolási Gépház-előfizetés < előfizetése >
Globális tárfiók Gépház tárfiók < a tárfiók >
Egyéni kódtár Gépház erőforrás Choose data source from current account (Adatforrás kiválasztása az aktuális fiókból)
Egyéni kódtár Gépház tárfiók < a tárfiók >
Egyéni kódtároló Gépház tároló < a tároló >
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 MyUdfMethod példában a lekérdezés által biztosított adatbemenetet , a futtatókörnyezeti motor által biztosított környezeti bemenetet StreamingContextdefiniálja.

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 használata MyUdfMethod nem változik, ahogy az a következő lekérdezésben is 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ő felhasználói egyéni kód mappájának gyökerébe lesz másolva, ha nincs kibontva. A zip "lapított" lesz, ha letörik.

  • 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