Door gebruiker gedefinieerde JavaScript-functies in Stream Analytics
Azure Stream Analytics ondersteunt door de gebruiker gedefinieerde functies die zijn geschreven in JavaScript. Met de uitgebreide set van String-, RegExp-, Math-, Array- en Date-methoden van JavaScript kunt u gemakkelijker complexe gegevenstransformaties maken met Stream Analytics-taken.
Overzicht
Door de gebruiker gedefinieerde JavaScript-functies ondersteunen staatloze, scalaire rekenfuncties die geen externe verbinding nodig hebben. De resultaatwaarde van een functie mag alleen een scalaire (enkelvoudige) waarde zijn. Nadat u een door de gebruiker gedefinieerde JavaScript-functie aan een taak hebt toegevoegd, kunt u de functie overal in de query als een ingebouwde scalaire functie gebruiken.
Hier volgen enkele scenario's waarin door de gebruiker gedefinieerde JavaScript-functies mogelijk interessant kunnen zijn:
- Het parseren en manipuleren van tekenreeksen die functies met reguliere expressies bevatten, bijvoorbeeld Regexp_Replace() en Regexp_Extract()
- Het (de)coderen van gegevens, bijvoorbeeld bij een conversie van binair naar hexadecimaal
- Het maken van rekenkundige berekeningen met Math-functies van JavaScript
- Het maken van matrixbewerkingen zoals sorteren, samenvoegen, zoeken en vullen
Hier volgen enkele dingen die u met een door de gebruiker gedefinieerde JavaScript-functie niet kunt doen in Stream Analytics:
- Externe REST-eindpunten aanroepen, bijvoorbeeld, het maken van een reverse IP-lookup of het ophalen van referentiegegevens uit een externe bron
- Serialisatie of deserialisatie van gebeurtenissen met aangepaste indeling uitvoeren voor invoer/uitvoer
- Aangepaste combinaties maken
Hoewel functies als Date.GetDate() of Math.random() niet zijn geblokkeerd in de definitie van functies, kunt u ze beter niet gebruiken. Deze functies resulteren niet telkens wanneer u ze aanroept hetzelfde resultaat. Bovendien houdt de Azure Stream Analytics-service geen logboek bij van functieaanroepen en de geretourneerde resultaten. Als een functie verschillende resultaten voor dezelfde gebeurtenissen retourneert, wordt herhaalbaarheid niet gegarandeerd wanneer een taak door u of door de Stream Analytics-service opnieuw wordt gestart.
Een door een JavaScript-gebruiker gedefinieerde functie aan uw taak toevoegen
Notitie
Deze stappen werken aan de Stream Analytics-taken die zijn geconfigureerd om te worden uitgevoerd in de cloud. Als uw Stream Analytics-taak is geconfigureerd om te worden uitgevoerd op Azure IoT Edge, gebruikt u in plaats daarvan Visual Studio en schrijft u de door de gebruiker gedefinieerde functie met C#.
Als u een door de gebruiker gedefinieerde JavaScript-functie in uw Stream Analytics-taak wilt maken, selecteert u Functies onder Taaktopologie. Selecteer vervolgens JavaScript UDF in het vervolgkeuzemenu + Toevoegen.
Vervolgens moet u de volgende eigenschappen opgeven en Opslaan selecteren.
| Eigenschap | Beschrijving |
|---|---|
| Functiealias | Voer een naam in om de functie in uw query aan te roepen. |
| Uitvoertype | Type dat wordt geretourneerd met behulp van door de gebruiker gedefinieerde JavaScript-functie naar uw Stream Analytics-query. |
| Functiedefinitie | Implementatie van uw JavaScript-functie die wordt uitgevoerd wanneer uw UDF wordt aangeroepen vanuit uw query. |
JavaScript-UDF’s testen en fouten oplossen
U kunt uw JavaScript UDF-logica testen en fouten opsporen in elke browser. Fouten opsporen en testen van de logica van deze door de gebruiker gedefinieerde functies wordt momenteel niet ondersteund in de Stream Analytics-portal. Zodra de functie werkt zoals verwacht, kunt u deze toevoegen aan de Stream Analytics-taak zoals hierboven wordt vermeld en vervolgens rechtstreeks vanuit uw query aanroepen. U kunt uw query-logica testen met JavaScript UDF met Stream Analytics-hulpprogramma's voor Visual Studio.
JavaScript-runtime-fouten worden beschouwd als onherstelbaar en worden weergegeven via het activiteitenlogboek. U haalt het logboek op door in Azure Portal naar uw project te gaan en Activiteitenlogboek te selecteren.
Een door de gebruiker gedefinieerde JavaScript-functie in een query aanroepen
U kunt uw JavaScript-functie in uw query eenvoudig aanroepen met behulp van de functiealias voorafgegaan door udf. Hier volgt een voorbeeld van een JavaScript UDF waarmee hexadecimale waarden worden geconverteerd naar een geheel getal dat wordt aangeroepen in een Stream Analytics-query.
SELECT
time,
UDF.hex2Int(offset) AS IntOffset
INTO
output
FROM
InputStream
Ondersteunde JavaScript-objecten
Door de gebruiker gedefinieerde JavaScript-functies in Azure Stream Analytics ondersteunen standaard ingebouwde JavaScript-objecten. Zie Algemene objecten voor een lijst van deze objecten.
Typeconversie van Stream Analytics en JavaScript
Er zijn verschillen in de typen die de querytaal van Stream Analytics en JavaScript ondersteunen. Deze tabel bevat de conversietoewijzingen tussen de twee:
| Stream Analytics | Javascript |
|---|---|
| bigint | Number (In JavaScript kunnen alleen gehele getallen tot exact 2^53 worden weergegeven) |
| DateTime | Date (JavaScript ondersteunt alleen milliseconden) |
| double | Aantal |
| nvarchar(MAX) | Tekenreeks |
| Record | Object |
| Matrix | Matrix |
| NULL | Null |
Hier volgen JavaScript-naar-Stream Analytics-conversies:
| Javascript | Stream Analytics |
|---|---|
| Aantal | Bigint (als het een rond getal tussen long.MinValue en long.MaxValue is; anders is het double) |
| Date | DateTime |
| Tekenreeks | nvarchar(MAX) |
| Object | Record |
| Matrix | Matrix |
| Null, niet gedefinieerd | NULL |
| Elk ander type (bijvoorbeeld een functie of fout) | Niet ondersteund (resulteert in een runtime-fout) |
JavaScript-computertaal is hoofdlettergevoelig en hoofdlettergebruik in de objectvelden in JavaScript-code moeten overeenkomen met hoofdlettergebruik in de velden in de binnenkomende gegevens. Met taken met compatibiliteitsniveau 1,0 worden velden van SQL SELECT-instructie geconverteerd naar kleine letters. Onder compatibiliteitsniveau 1,1 en hoger, hebben velden uit de SELECT-instructie hetzelfde hoofdlettergebruik dat is opgegeven in de SQL-query.
Andere door de gebruiker gedefinieerde JavaScript-functiepatronen
Geneste JSON naar uitvoer schrijven
Als u een follow-up verwerkingsstap hebt die de uitvoer van een Stream Analytics-taak gebruikt als invoer, als die invoer een JSON-indeling vereist, kunt u een JSON-tekenreeks naar uitvoer schrijven. In het volgende voorbeeld wordt de functie JSON.stringify() aangeroepen om alle naam-/waarde-paren van de invoer te verpakken en als één tekenreekswaarde in de uitvoer te schrijven.
Definitie van een door de gebruiker gedefinieerde JavaScript-functie:
function main(x) {
return JSON.stringify(x);
}
Voorbeeldquery:
SELECT
DataString,
DataValue,
HexValue,
UDF.jsonstringify(input) As InputEvent
INTO
output
FROM
input PARTITION BY PARTITIONID
Te verwerken tekenreeks naar JSON-object converteren
Als u een tekenreeksveld hebt in JSON en dit wilt converteren naar een JSON-object om in een JavaScript-UDF te verwerken, kunt u de functie JSON.parse() gebruiken om een JSON-object te maken dat vervolgens kan worden gebruikt.
Definitie van een door de gebruiker gedefinieerde JavaScript-functie:
function main(x) {
var person = JSON.parse(x);
return person.name;
}
Voorbeeldquery:
SELECT
UDF.getName(input) AS Name
INTO
output
FROM
input
Try/catch gebruiken voor foutafhandeling
Try/catch-blokken kunnen u helpen bij het identificeren van problemen met onjuiste invoergegevens die worden doorgegeven aan een JavaScript-UDF.
Definitie van een door de gebruiker gedefinieerde JavaScript-functie:
function main(input, x) {
var obj = null;
try{
obj = JSON.parse(x);
}catch(error){
throw input;
}
return obj.Value;
}
Voorbeeldquery: Geef een volledige record door als eerste parameter, zodat deze kan worden geretourneerd als er een fout optreedt.
SELECT
A.context.company AS Company,
udf.getValue(A, A.context.value) as Value
INTO
output
FROM
input A
toLocaleString()
De toLocaleString-methode in JavaScript kan worden gebruikt om een taalgevoelige tekenreeks te retourneren die de datum- en tijdgegevens vertegenwoordigt vanwaaruit deze methode wordt aangeroepen. Hoewel Azure Stream Analytics alleen UTC-datums en -tijden accepteert als tijdstempel van het systeem, kan deze methode worden gebruikt om de systeemtijdstempel te converteren naar een andere landinstelling en tijdzone. Deze methode volgt hetzelfde implementatiegedrag als in Internet Explorer.
Definitie van een door de gebruiker gedefinieerde JavaScript-functie:
function main(datetime){
const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
return datetime.toLocaleDateString('de-DE', options);
}
Voorbeeldquery: Een datum/tijd als invoerwaarde doorgeven
SELECT
udf.toLocaleString(input.datetime) as localeString
INTO
output
FROM
input
De uitvoer van deze query is de invoer-datum/tijd in de-DE met de opgegeven opties.
Samstag, 28. Dezember 2019
Logboekregistratie voor gebruikers
Met het mechanisme voor logboekregistratie kunnen gebruikers aangepaste gegevens vastleggen terwijl een taak wordt uitgevoerd. Logboekgegevens kunnen worden gebruikt om fouten op te sporen of de juistheid van de aangepaste code in realtime te beoordelen. Dit mechanisme is beschikbaar via drie verschillende methoden.
Console.Info()
Console.Info methode wordt gebruikt voor het vastleggen van algemene informatie tijdens het uitvoeren van code. Met deze methode worden gegevens in een logboek opgenomen zonder de berekening te onderbreken. Het bericht dat wordt geregistreerd, wordt gemarkeerd als Informatief op gebeurtenisniveau.
console.info('my info message');
Console.Warn()
De methode Console.Warn wordt gebruikt voor het vastleggen van gegevens die mogelijk niet juist zijn of worden verwacht, maar die nog steeds worden geaccepteerd voor berekeningen. Deze methode onderbreekt de berekening niet en wordt weer uitgevoerd nadat de methode is geretourneerd. Het bericht dat wordt geregistreerd, wordt gemarkeerd als Waarschuwing op gebeurtenisniveau.
console.warn('my warning message');
Console.Error() en Console.Log()
De methode Console.Error wordt alleen gebruikt voor het vastleggen van foutgevallen waarbij de code niet meer kan worden uitgevoerd. Deze methode genereert een uitzondering met de foutinformatie die wordt opgegeven als de invoerparameter en de taak wordt niet meer uitgevoerd. Het in het logboek vastgelegde foutbericht wordt gemarkeerd als Fout op gebeurtenisniveau.
console.error('my error message');
U kunt logboekberichten openen via de Diagnostische logboeken.
atob() en btoa()
De methode btoa() kan worden gebruikt om een ASCII-tekenreeks te coderen in Base64. Dit wordt meestal gedaan om gegevens over te dragen in een binaire indeling. De methode atob() kan worden gebruikt voor het decoderen van een tekenreeks met gegevens die zijn gecodeerd in Base64 naar een ASCII-tekenreeksindeling.
var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);