Användardefinierade JavaScript-funktioner i Azure Stream Analytics
Azure Stream Analytics stödjer användardefinierade JavaScript-funktioner. Med de omfattande metoderna String, RegExp, Math, Array och Date som JavaScript tillhandahåller blir komplexa datatransformeringar med Stream Analytics-jobb enklare att skapa.
Översikt
Användardefinierade JavaScript-funktioner har stöd för tillståndslösa, beräkningsbaserade skalärfunktioner som inte kräver extern anslutning. Returvärdet för en funktion kan endast vara ett skalärvärde (enkelt). När du lägger till en användardefinierad JavaScript-funktion i ett jobb kan använda funktionen var som helst i frågan, som en inbyggd skalärfunktion.
Här följer några scenarier där användardefinierade JavaScript-funktioner kan vara användbara:
- Tolka och manipulera strängar som har funktioner med reguljära uttryck, till exempel Regexp_Replace() och Regexp_Extract()
- Avkoda och koda data, till exempel konvertering av binärt format till hexadecimalt
- Utföra matematiska beräkningar med JavaScript Math Functions
- Utföra matrisåtgärder som sortering, koppling, sökning och fyllning
Här är några saker som du inte kan göra med en användardefinierad JavaScript-funktion i Stream Analytics:
- Anropa externa REST-slutpunkter, till exempel att göra omvänd IP-sökning eller hämta referensdata från en extern källa
- Utför anpassade serialisering eller avserialisering av händelseformat på indata/utdata
- Skapa anpassade samlingar
Även om funktioner som Date.GetDate() eller Math.random() inte blockeras i funktionsdefinitionen bör du undvika 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 olika resultat för samma händelser garanteras inte repeterbarhet när ett jobb startas om av dig eller av Stream Analytics-tjänsten.
Lägga till en användardefinierad JavaScript-funktion i jobbet
Anteckning
De här stegen fungerar på Stream Analytics-jobb som konfigurerats för att köras i molnet. Om Stream Analytics-jobbet har konfigurerats för att köras på Azure IoT Edge använder du i stället Visual Studio och skriver den användardefinierade funktionen med hjälp av C#.
Om du vill skapa en användardefinierad JavaScript-funktion i Stream Analytics-jobbet väljer du Funktioner under Jobbtopologi. Välj sedan JavaScript UDF i listrutan +Lägg till .
Du måste sedan ange följande egenskaper och välja Spara.
| Egenskap | Beskrivning |
|---|---|
| Funktionsalias | Ange ett namn för att anropa funktionen i frågan. |
| Utdatatyp | Typ som returneras av din Användardefinierade JavaScript-funktion till Stream Analytics-frågan. |
| Funktionsdefinition | Implementering av javascript-funktionen som körs varje gång din UDF anropas från din fråga. |
Testa och felsöka JavaScript-UDF:er
Du kan testa och felsöka din JavaScript UDF-logik i valfri webbläsare. Felsökning och testning av logiken för dessa användardefinierade funktioner stöds för närvarande inte i Stream Analytics-portalen. När funktionen fungerar som förväntat kan du lägga till den i Stream Analytics-jobbet enligt ovan och sedan anropa den direkt från frågan. Du kan testa din frågelogik med JavaScript UDF med Stream Analytics-verktyg för Visual Studio.
JavaScript-körningsfel betraktas som allvarliga och exponeras via aktivitetsloggen. För att hämta loggen i Azure Portal går du till jobbet och väljer aktivitetsloggen.
Anropa en användardefinierad JavaScript-funktion i en fråga
Du kan enkelt anropa din JavaScript-funktion i din fråga med hjälp av funktionsaliaset som är prefixet med udf. Här är ett exempel på en JavaScript UDF som konverterar hexadecimala värden till heltal som anropas i en Stream Analytics-fråga.
SELECT
time,
UDF.hex2Int(offset) AS IntOffset
INTO
output
FROM
InputStream
JavaScript-objekt som stöds
Användardefinierade JavaScript-funktioner i Azure Stream Analytics stödjer inbyggda standardobjekt i JavaScript. En lista över de här objekten finns i Globala objekt.
Stream Analytics och JavaScript typkonvertering
Det finns skillnader i vilka typer som Stream Analytics frågespråk och JavaScript stödjer. Den här tabellen visar konverteringsmappningar mellan dessa:
| Stream Analytics | JavaScript |
|---|---|
| bigint | Siffra (JavaScript kan bara representera heltal upp till exakt 2^53) |
| DateTime | Datum (JavaScript stöder endast millisekunder) |
| double | Tal |
| nvarchar(MAX) | Sträng |
| Post | Objekt |
| Matris | Matris |
| NULL | Null |
Här är konverteringarna från JavaScript till Stream Analytics:
| JavaScript | Stream Analytics |
|---|---|
| Tal | Bigint (om talet är avrundat och mellan long.MinValue och long.MaxValue, i annat fall stöds det inte) |
| Date | DateTime |
| Sträng | nvarchar(MAX) |
| Objekt | Post |
| Matris | Matris |
| Null, odefinierad | NULL |
| Annan typ (till exempel en funktion eller fel) | Stöds inte (resulterar i körningsfel) |
JavaScript-språket är skiftlägeskänsligt och höljet för objektfälten i JavaScript-koden måste matcha höljet för fälten i inkommande data. Jobb med kompatibilitetsnivå 1.0 konverterar fält från SQL SELECT-instruktionen till gemener. Under kompatibilitetsnivå 1.1 och senare har fält från SELECT-instruktionen samma hölje som anges i SQL-frågan.
Andra mönster för användardefinierade JavaScript-funktioner
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. I nästa exempel anropar den funktionen JSON.stringify() för att packa alla namn-/värdepar för indata och sedan skriva dem som ett enda strängvärde i utdata.
Definiera en användardefinierad JavaScript-funktion:
function main(x) {
return JSON.stringify(x);
}
Exempelfråga:
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 sedan kan användas.
Definiera en användardefinierad JavaScript-funktion:
function main(x) {
var person = JSON.parse(x);
return person.name;
}
Exempelfråga:
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 felaktiga indata som skickas till en JavaScript UDF.
Definiera en användardefinierad JavaScript-funktion:
function main(input, x) {
var obj = null;
try{
obj = JSON.parse(x);
}catch(error){
throw input;
}
return obj.Value;
}
Exempelfråga: Skicka hela posten som första parameter så att den kan returneras om det uppstår 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 kan användas för att returnera en språkkänslig sträng som representerar datumtidsdata från där den här metoden anropas. Även om Azure Stream Analtyics endast accepterar UTC-datumtid som systemtidsstämpel, kan den här metoden användas för att täcka systemtidsstämpeln till ett annat språk och tidszon. Den här metoden följer samma implementeringsbeteende som den som är tillgänglig i Internet Explorer .
Definiera en användardefinierad JavaScript-funktion:
function main(datetime){
const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
return datetime.toLocaleDateString('de-DE', options);
}
Exempelfråga: Skicka ett datetime som indatavärde
SELECT
udf.toLocaleString(input.datetime) as localeString
INTO
output
FROM
input
Utdata för den här frågan blir indatadatumtiden i de-DE med de angivna alternativen.
Samstag, 28. Dezember 2019
Användarloggning
Loggningsmekanismen gör det möjligt för användare att samla in anpassad information när ett jobb körs. Loggdata kan användas för att felsöka eller utvärdera korrektheten i den anpassade koden i realtid. Den här mekanismen är tillgänglig via tre olika metoder.
Console.Info()
Console.Info-metoden används för att logga allmän information under kodkörningen. Den här metoden loggar data utan att avbryta beräkningen. Meddelandet som loggas markeras som information på händelsenivå.
console.info('my info message');
Console.Warn()
Console.Warn-metoden används för att logga data som kanske inte är korrekta eller förväntade men som fortfarande accepteras för beräkning. Den här metoden avbryter inte beräkningen och fortsätter att köras när metoden har returnerats. Meddelandet som loggas markeras som händelsenivåvarning.
console.warn('my warning message');
Console.Error() och Console.Log()
Console.Error-metoden används bara för att logga felfall där koden inte kan fortsätta att köras. Den här metoden genererar ett undantag med felinformationen som tillhandahålls eftersom indataparametern och jobbet slutar att köras. Det loggade felmeddelandet markeras som händelsenivåfel.
console.error('my error message');
Du kan komma åt loggmeddelanden via diagnostikloggarna.
atob() och btoa()
Metoden btoa() kan användas för att koda en ASCII-sträng till Base64. Detta görs vanligtvis för att överföra data i binärt format. Atob()-metoden kan användas för att avkoda en sträng med data som kodas i Base64 till ett ASCII-strängformat.
var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);