Användardefinierade JavaScript-funktioner i Azure Stream Analytics

Azure Stream Analytics stödjer användardefinierade JavaScript-funktioner. Genom att använda den rika uppsättningen av String-, RegExp-, Math-, Array- och Date-metoder som JavaScript erbjuder, kan du skapa komplexa datatransformationer i Stream Analytics-jobb. Användardefinierade JavaScript-funktioner stöder tillståndslösa skalära funktioner som endast beräknas och som inte kräver extern anslutning. Returvärdet för en funktion kan endast vara ett skalärvärde (enkelt). När du har lagt till en användardefinierad JavaScript-funktion i ett jobb kan du använda funktionen var som helst i frågan, precis som en inbyggd skalärfunktion.

Den här artikeln beskriver när man ska använda JavaScript användardefinierade funktioner och hur man definierar och anropar dem i dina Stream Analytics-jobb.

När man ska använda en JavaScript-användardefinierad funktion

Här följer några scenarier där användardefinierade JavaScript-funktioner kan vara användbara:

• Att tolka och manipulera strängar med hjälp av reguljära uttrycksfunktioner, till exempel Regexp_Replace() och Regexp_Extract()
• Avkoda och koda data, till exempel konvertering av binärt format till hexadecimalt
• Att göra matematiska beräkningar med hjälp av JavaScript-matematikfunktioner
• Utföra matrisåtgärder som sortering, koppling, sökning och fyllning

Här är några saker du inte kan göra genom att använda en användardefinierad JavaScript-funktion i Stream Analytics:

• Anropa externa REST-endpoints, till exempel genom att göra omvänd IP-uppslagning eller hämta referensdata från en extern källa
• Utför serialisering eller deserialisering av anpassade händelseformat på in- eller utdata
• Skapa anpassade aggregat

Även om funktioner som Date.GetDate() eller Math.random() inte blockeras i funktionsdefinitionen, undvik att använda dem. Dessa funktioner returnerar inte samma resultat varje gång du anropar dem, och Azure Stream Analytics-tjänsten för inte en journal över funktionsanrop och returnerade resultat. Om en funktion returnerar ett annat resultat vid samma händelser är upprepbarhet inte garanterad när du eller Stream Analytics-tjänsten startar om jobbet.

Definiera en JavaScript-användardefinierad funktion i Azure portal

För ett Stream Analytics-jobb som körs i molnet, lägg till en användardefinierad JavaScript-funktion från Funktioner-sidan under Jobbtopologi, där +Lägg till-menyn innehåller ett JavaScript-UDF-alternativ .

En funktionsdefinition består av följande egenskaper:

Testa och felsök JavaScript UDF-logik

Eftersom Stream Analytics-portalen inte stödjer felsökning och testning av logiken i dessa användardefinierade funktioner kan du testa och felsöka din JavaScript UDF-logik i vilken webbläsare som helst. När funktionen fungerar som förväntat är den redo att läggas till i Stream Analytics-jobbet och anropa direkt från din fråga. Du kan också testa din frågelogik med en JavaScript-UDF genom att använda Stream Analytics-verktygen för Visual Studio.

Stream Analytics behandlar JavaScript-runtimefel som fatala och visar dem via aktivitetsloggen. Loggen finns tillgänglig i Azure-portalen från ditt jobbs aktivitetssida.

Anropa en användardefinierad JavaScript-funktion i en fråga

För att anropa din JavaScript-funktion i din fråga, använd funktionsaliaset med förenamnet udf. Följande exempel visar en JavaScript-UDF som omvandlar hexadecimala värden till ett heltal i en Stream Analytics-fråga.

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

JavaScript-objekt som stöds

Azure Stream Analytics JavaScript användardefinierade funktioner stödjer de standardiserade, inbyggda JavaScript-objekten. Dessa objekt ger dina funktioner tillgång till gemensamma sträng-, matematik-, array- och datumoperationer utan någon extra konfiguration. För en komplett lista över tillgängliga objekt, se Globala objekt. Eftersom Stream Analytics-frågespråket och JavaScript inte delar samma typsystem, konverterar Stream Analytics värden när de passerar mellan de två.

Stream Analytics och JavaScript typkonvertering

Stream Analytics-frågespråket och JavaScript har stöd för olika typer. Den här tabellen visar konverteringsmappningar mellan dessa:

Här är konverteringarna från JavaScript till Stream Analytics:

JavaScript är skiftlägeskänsligt, och användningen av versaler och gemener i objektfälten i JavaScript-koden måste stämma överens med användningen i fälten i inkommande data. Jobb med kompatibilitetsnivå 1.0 konverterar fält från SQL SELECT-satsen till gemener. Under kompatibilitetsnivå 1.1 och högre har fält från SELECT-satsen samma chassing som specificerats i SQL-frågan.

Vanliga funktionsmönster

Följande mönster visar vanliga sätt att använda JavaScripts användardefinierade funktioner för att transformera data i dina Stream Analytics-frågor. Varje mönster innehåller en funktionsdefinition och en exempelfråga som anropar den.

Skriva kapslad JSON till utdata

Om du har ett bearbetningssteg för uppföljning som använder Stream Analytics-jobbets utdata som indata, och det kräver ett JSON-format, kan du skriva en JSON-sträng till utdata. Följande funktionsdefinition anropar JSON.stringify() -funktionen för att packa alla namn/värde-par i indata och sedan skriva dem som ett enda strängvärde i utdata.

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

En Stream Analytics-fråga anropar funktionen som visas i följande exempel.

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

Omvandla sträng till JSON-objekt att bearbeta

Om du har ett strängfält som är JSON och vill konvertera det till ett JSON-objekt för bearbetning i en JavaScript UDF, kan du använda funktionen JSON.parse() för att skapa ett JSON-objekt som du sedan kan använda. Följande funktionsdefinition tolkar strängen och returnerar en egenskap från det resulterande objektet.

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

En Stream Analytics-fråga anropar funktionen som visas i följande exempel.

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

Använda try/catch för felhantering

Try/catch-block kan hjälpa dig att identifiera problem med felaktigt formaterade indata som du skickar till en JavaScript-UDF. Följande funktionsdefinition använder ett try/catch-block för att hantera tolkningsfel.

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

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

I följande exempelfråga skickar du hela posten som första parameter så att funktionen kan returnera den om det finns ett fel.

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

toLocaleString()

Metoden toLocaleString i JavaScript returnerar en språkkänslig sträng som representerar datum-tid-data från vilken du anropar metoden. Även om Azure Stream Analytics endast accepterar UTC datum-tid som systemtidsstämpel, kan du använda denna metod för att konvertera systemets tidsstämpel till en annan plats och tidszon. Denna metod följer samma implementeringsbeteende som den som finns tillgänglig i Internet Explorer. Följande funktionsdefinition konverterar inmatat datum och tid till språkområdet de-DE.

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

I följande exempelfråga anges en date-time som indatavärde.

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

Resultatet från denna fråga är inmatningsdatumet i de-DE med de tillgängliga alternativen.

Samstag, 28. December 2019

Användarloggning

Loggning är den mekanism som Azure Stream Analytics använder för att fånga anpassad information från en JavaScript-användardefinierad funktion medan ett jobb körs. Eftersom ett körjobb annars är ogenomskinligt ger loggdata dig insyn i beteendet och korrektheten i din anpassade kod i realtid. Varje loggmeddelande bär på en händelsenivå som visar hur betydelsefullt meddelandet är och om jobbet kan fortsätta köras.

Informationsmeddelanden kommer från console.info() -metoden, såsom console.info('my info message');. Denna nivå registrerar allmän information under exekveringen och avbryter inte beräkningen. Varningsmeddelanden kommer från console.warn() -metoden, såsom console.warn('my warning message');. Denna nivå registrerar data som kan vara oväntad men ändå är acceptabel för beräkning, så jobbet fortsätter att köras. Felmeddelanden kommer från metoderna console.error() och console.log(), såsom console.error('my error message');. Dessa metoder gäller endast i fall där koden inte kan fortsätta, så de kastar ett undantag med den tillhandahållna felinformationen och stoppar jobbet.

Du kan komma åt loggmeddelanden via diagnostikloggarna.

atob() och btoa()

Stream Analytics stöder två metoder för Base64-konvertering, vilket är ett vanligt sätt att koda binär data som text. Btoa()-metoden kodar en ASCII-sträng till Base64, och atob()-metoden avkodar en sträng med Base64-kodad data tillbaka till en ASCII-sträng. I följande exempel btoa() kodar du en ASCII-sträng och atob() avkodar sedan resultatet tillbaka till originalsträngen.

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

Relaterat innehåll

• Maskininlärning UDF
• C# användardefinierade funktioner