JavaScript felhasználó által definiált függvények az Azure Stream Analyticsben

Az Azure Stream Analytics támogatja a JavaScript nyelven írt felhasználói függvényeket. A JavaScript által kínált gazdag String, RegExp, Math, Array és Date módszerek használatával összetett adattranszformációkat hozhatsz létre a Stream Analytics feladatokban. A JavaScript felhasználó által definiált függvények támogatják az állapot nélküli, csak számítással rendelkező skaláris függvényeket, amelyek nem igényelnek külső kapcsolatot. Egy függvény visszaadott értéke csak skaláris (egyetlen) érték lehet. Miután hozzáadott egy felhasználói JavaScript-függvényt egy feladathoz, bárhol használhatja a függvényt a lekérdezésben, egy beépített skaláris függvényhez hasonlóan.

Ez a cikk bemutatja, mikor érdemes használni JavaScript felhasználódefiniált függvényeket, és hogyan definiálhatod és hívhatod azokat a Stream Analytics feladataidban.

Mikor kell JavaScript felhasználó-definiált függvényt használni

Az alábbiakban bemutatunk néhány forgatókönyvet, amelyekben hasznosnak találhatja a felhasználói JavaScript-függvényeket:

• A sorozatok elemzése és manipulálása reguláris kifejezési függvényekkel, például Regexp_Replace() és Regexp_Extract()
• Adatok dekódolása és kódolása, például bináris adatok átalakítása hexadecimális adatokká.
• Matematikai számítások JavaScript matematikai függvények használatával
• Tömbműveletek, például rendezés, illesztés, keresés és kitöltés végrehajtása

Íme néhány dolog, amit nem lehet JavaScript felhasználóval definiált függvényrel a Stream Analytics rendszerében:

• Hívjunk külső REST végpontokat, például fordított IP keresést végezzen, vagy külső forrásból származó referenciaadatokat húzzunk
• Egyedi eseményformátum serializációt vagy deserializációt végezzen bemeneteken vagy kimeneteken
• Egyéni összesítések létrehozása.

Bár olyan függvények, mint a Date.GetDate() vagy a Math.random() nincsenek blokkolva a függvénydefinícióban, kerüld a használatukat. Ezek a függvények nem minden híváskor ugyanazt az eredményt adják vissza, és az Azure Stream Analytics szolgáltatás nem tartja meg a függvényhívások naplóját és az eredményeket. Ha egy függvény ugyanazon eseményen más eredményt ad vissza, az ismétlékenység nem garantált, amikor te vagy a Stream Analytics szolgáltatás újraindítod a munkát.

Definiálj JavaScript felhasználó által definiált függvényt az Azure portálban

Egy felhőben futó Stream Analytics feladathoz adj hozzá JavaScript felhasználó által definiált függvényt a Függvények oldalról a Job Topology alatt, ahol a +Add menüben található JavaScript UDF opció.

Megjegyzés

Ez a tapasztalat a felhőben futásra konfigurált Stream Analytics feladatokra is vonatkozik. Ha a Stream Analytics-feladat úgy van konfigurálva, hogy az Azure IoT Edge-en fusson, használja a Visual Studiót, és írja meg a felhasználó által definiált függvényt a C# használatával.

A függvénydefiníció a következő tulajdonságokból áll:

Tulajdonság	Leírás
Függvény álnév	Az a név, amely a lekérdezésben aktiválja a függvényt.
Kimeneti típus	Az a típus, amelyet a JavaScript felhasználó által definiált függvény visszaad a Stream Analytics lekérdezésedhez.
Függvénydefiníció	A JavaScript funkció megvalósítása, amely minden alkalommal fut, amikor az UDF-et a lekérdezésedből hívják elő.

JavaScript UDF logika tesztelése és hibaelhárítása

Mivel a Stream Analytics portál nem támogatja ezeknek a felhasználó-definiált függvényeknek a logikáját és hibakeresését, bármelyik böngészőben tesztelheted és debugálhatod a JavaScript UDF logikádat. Amikor a függvény a várakozásoknak megfelelően működik, készen áll arra, hogy hozzáadja a Stream Analytics feladathoz, és közvetlenül a lekérdezésből indítsa meg. A lekérdezési logikát JavaScript UDF-fel is tesztelheted a Visual Studio Stream Analytics eszközeivel.

A Stream Analytics végzetesnek tekinti a JavaScript futtatóidejű hibáit, és feltárja azokat az Activity naplón keresztül. A napló elérhető az Azure portálban a munkád Tevékenységi napló oldalán.

Egy lekérdezésben felhasználó által definiált JavaScript-függvény meghívása

A JavaScript függvény meghívásához használja az udf előtagú alias függvényt. A következő példa egy JavaScript UDF-et mutat be, amely egy Stream Analytics lekérdezésben hexadecimális értékeket egész számra alakít át.

    SELECT
        time,
        UDF.hex2Int(offset) AS IntOffset
    INTO
        output
    FROM
        InputStream

Támogatott JavaScript-objektumok

Azure Stream Analytics JavaScript felhasználó-definiált függvényei támogatják a szabványos, beépített JavaScript objektumokat. Ezek az objektumok hozzáférést biztosítanak a függvényeidnek a közös string-, matematika-, tömb- és dátumműveletekhez extra konfiguráció nélkül. A rendelkezésre álló objektumok teljes listájáért lásd: Globális objektumok. Mivel a Stream Analytics lekérdezési nyelv és a JavaScript nem ugyanazt a típustípust használja, a Stream Analytics az értékeket átalakítja, ahogy azok a kettő között váltak.

Típusátalakítás a Stream Analytics és a JavaScript között

A Stream Analytics lekérdezési nyelv és a JavaScript különböző típusokat támogat. Az alábbi táblázat a kettő közötti átalakítás megfeleléseit tartalmazza:

Stream Analytics	JavaScript
bigint	Szám (a JavaScript legfeljebb pontosan a 2^53-ig tudja a számokat kezelni)
Dátum/idő	Dátum (a JavaScript csak az ezredmásodperceket támogatja)
double	Szám
nvarchar(MAX)	Sztring
Rögzítés	Objektum
Tömb	Tömb
NULL	Null

A JavaScriptről a Stream Analyticsre történő átalakítások:

JavaScript	Stream Analytics
Szám	Bigint (ha a szám kerek és a long.MinValue és a long.MaxValue közé esik, máskülönben double)
Dátum	Dátum/idő
Sztring	nvarchar(MAX)
Objektum	Rögzítés
Tömb	Tömb
Null, nem definiált	NULL
Bármely más típus (például függvény vagy hiba)	Nem támogatott (futásidejű hibát eredményez)

A JavaScript kisbetűérzékeny, és a JavaScript kódban az objektummezők burkosításának meg kell egyeznie a bejövő adatok mezői burkosításával. A kompatibilitási szint 1.0 esetén a mezőket SQL SELECT utasításból kisbetűre alakítják át. Kompatibilitási szint 1.1 és annál magasabb szinten a SELECT utasítás mezői ugyanazt a burkotokat kapják, mint az SQL lekérdezésben megadva.

Gyakori funkcióminták

Az alábbi minták gyakori módokat mutatnak be JavaScript felhasználódefiniált függvények használatára az adatok átalakítására a Stream Analytics lekérdezéseiben. Minden minta tartalmaz egy függvénydefiníciót és egy mintalekérdezést, amely ezt megidézi.

Beágyazott JSON írása a kimenetbe

Ha van még egy további feldolgozási lépés, amely a Stream Analytics-feladat kimenetét használja a bemeneteként, és JSON-formátumot igényel, a kimenetbe írhat JSON-sztringet. A következő függvénydefiníció a JSON.stringify() függvényt hívja, hogy becsomagolja az összes bemeneti név/érték párt, majd egyetlen stringértékként írja meg őket a kimenetben.

function main(x) {
return JSON.stringify(x);
}

Egy Stream Analytics lekérdezés indítja el a függvényt, ahogy az alábbi példában látható.

SELECT
    DataString,
    DataValue,
    HexValue,
    UDF.jsonstringify(input) As InputEvent
INTO
    output
FROM
    input PARTITION BY PARTITIONID

Sztring átalakítása JSON-objektummá feldolgozáshoz

Ha van egy JSON string meződ, és szeretnéd JSON objektummá konvertálni feldolgozásra JavaScript UDF-ben, a JSON.parse() függvényrel létrehozhatsz egy JSON objektumot, amit aztán használhatsz. A következő függvénydefiníció feldolgozza a karakterláncot, és visszaadja a létrejövő objektum egyik tulajdonságát.

function main(x) {
var person = JSON.parse(x);  
return person.name;
}

Egy Stream Analytics lekérdezés indítja el a függvényt, ahogy az alábbi példában látható.

SELECT
    UDF.getName(input) AS Name
INTO
    output
FROM
    input

A hibakezeléshez használja a try/catch függvényt

A try/catch blokkok segíthetnek azonosítani a hibás bemeneti adatokkal kapcsolatos problémákat, amelyeket JavaScript UDF-be passzol. Az alábbi függvénydefiníció try/catch blokkot használ az elemzési hibák kezelésére.

function main(input, x) {
    var obj = null;

    try{
        obj = JSON.parse(x);
    }catch(error){
        throw input;
    }
    
    return obj.Value;
}

A következő mintalekérdezésben az egész rekordot továbbítod első paraméterként, hogy a függvény vissza tudja adni a hibát.

SELECT
    A.context.company AS Company,
    udf.getValue(A, A.context.value) as Value
INTO
    output
FROM
    input A

toLocaleString()

A JavaScript toLocaleString metódusa egy nyelvérzékeny stringet ad vissza, amely a dátum-idő adatokat képviseli, onnan hívjuk a metódust. Bár az Azure Stream Analytics csak az UTC dátum-időt fogadja el rendszer időbélyegként, ezt a módszert használhatod a rendszer időbélyegének más helyre és időzónára konvertálására. Ez a módszer ugyanazt a megvalósítási viselkedést követi, mint az Internet Explorer-ben elérhető. A következő függvénydefiníció a bemeneti dátum- és időértéket a de-DE területi beállításnak megfelelőre alakítja.

function main(datetime){
    const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
    return datetime.toLocaleDateString('de-DE', options);
}

A következő mintalekérdezésben egy dátumidőt adunk át bemeneti értékként.

SELECT
    udf.toLocaleString(input.datetime) as localeString
INTO
    output
FROM
    input

A lekérdezés kimenete a bemeneti datetime de-DE formátumban, a megadott beállításokkal.

Samstag, 28. December 2019

Felhasználói naplózás

A naplózás az a mechanizmus, amelyet az Azure Stream Analytics használ, hogy egyedi információkat gyűjtsen egy JavaScript felhasználó által definiált függvényből egy munka futása közben. Mivel egy futó munka egyébként átláthatatlan, a naplóadatok valós időben láthatást nyújtanak az egyedi kódod viselkedésére és helyességére. Minden naplóüzenet tartalmaz egy eseményszintet, amely jelzi, mennyire jelentős az üzenet, és hogy a munka folytatható-e a feladat.

Az információs üzenetek az console.info() módszerből származnak, például console.info('my info message');. Ez a szint általános információkat rögzít a végrehajtás során, és nem szakítja meg a számítást. Figyelmeztető üzenetek a console.warn() módszerből származnak, például console.warn('my warning message');. Ez a szint olyan adatokat rögzít, amelyek váratlanok lehetnek, de számításhoz mégis elfogadhatóak, így a munka tovább fut. A hibaüzenetek a console.error() és a console.log() metódusokból származnak, például console.error('my error message');. Ezek a módszerek csak akkor érvényesek, amikor a kód nem folytatható, ezért kivételt adnak a megadott hibainformációval, és leállítják a munkát.

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

atob() és btoa()

A Stream Analytics két Base64 átalakítási módszert támogat, ami egy gyakori módja a bináris adatok szövegként történő kódolásának. A btoa() módszer egy ASCII stringet kódol Base64-be, az atob() módszer pedig egy Base64-re kódolt adatsort dekódol vissza egy ASCII stringbe. A következő példában a btoa() egy ASCII-karakterláncot kódol, a atob() pedig ezután visszadekódolja az eredményt az eredeti karakterlánccá.

var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);

Kapcsolódó tartalom

• Gépi tanulás UDF
• C# felhasználó által definiált függvények