Uživatelem definované funkce JavaScriptu v Azure Stream Analytics

Azure Stream Analytics podporuje uživatelem definované funkce, které jsou napsané v jazyce JavaScript. Použitím bohaté sady metod String, RegExp, Math, Array a Date , které JavaScript nabízí, můžete vytvářet složité datové transformace v pracovních pozicích Stream Analytics. Uživatelsky definované funkce v jazyce JavaScript podporují bezstavové skalární funkce určené pouze pro výpočty, které nevyžadují externí připojení. Návratovou hodnotou funkce může být jenom skalární (jediná) hodnota. Po přidání uživatelem definované funkce jazyka JavaScript do úlohy lze danou funkci použít kdekoli v dotazu jako integrovanou skalární funkci.

Tento článek popisuje, kdy používat uživatelsky definované funkce v JavaScriptu a jak je definovat a volat ve svých pracovních pozicích v oblasti Stream Analytics.

Kdy použít uživatelsky definovanou funkcí v JavaScriptu

Některé scénáře, ve kterých můžou být uživatelem definované funkce jazyka JavaScript užitečné:

• Parsování a manipulace s řetězci pomocí regulárních výrazových funkcí, například Regexp_Replace() a Regexp_Extract()
• Dekódování a kódování dat, například převod z binární do hexadecimální podoby
• Matematické výpočty pomocí JavaScriptových matematických funkcí
• Provádění operací s poli, jako je řazení, spojení, hledání a vyplnění

Zde je několik věcí, které nelze udělat pomocí uživatelsky definované funkce v JavaScriptu v Stream Analytics:

• Volat externí koncové body REST API, například pro provádění zpětného vyhledávání IP nebo získávání referenčních dat z externího zdroje
• Provést vlastní serializaci nebo deserializaci formátu událostí na vstupech nebo výstupech
• Vytváření vlastních agregací

Ačkoliv funkce jako Date.GetDate() nebo Math.random() nejsou v definici funkcí blokovány, vyhněte se jejich použití. Tyto funkce nevrací stejný výsledek pokaždé, když je zavoláte, a služba Azure Stream Analytics neuchová deník vyvolání a vrácených výsledků. Pokud funkce vrátí jiný výsledek ve stejných událostech, není zaručena opakovatelnost, když vy nebo služba Stream Analytics restartujete práci.

Definujte uživatelsky definovanou funkci v JavaScriptu v portálu Azure

Pro práci Stream Analytics, která běží v cloudu, přidejte uživatelsky definovanou funkci v JavaScriptu ze stránky Functions v Job Topology, kde nabídka +Add obsahuje možnost JavaScript UDF .

Poznámka:

Tato zkušenost platí pro úlohy Stream Analytics nastavené pro spuštění v cloudu. Pokud je vaše úloha Stream Analytics nakonfigurovaná tak, aby běžela v Azure IoT Edge, místo toho použijte Visual Studio a napište uživatelem definovanou funkci pomocí jazyka C#.

Definice funkce se skládá z následujících vlastností:

Vlastnost	Popis
Alias funkce	Název, který vyvolává funkci ve vašem dotazu.
Typ výstupu	Typ, který JavaScriptová uživatelsky definovaná funkce vrací do vašeho dotazu Stream Analytics.
Definice funkce	Implementace vaší JavaScriptové funkce, která se spustí pokaždé, když je UDF vyvolán z vašeho dotazu.

Testování a řešení problémů s JavaScriptovou UDF logikou

Protože portál Stream Analytics nepodporuje ladění a testování logiky těchto uživatelsky definovaných funkcí, můžete testovat a ladit svou JavaScript UDF logiku v jakémkoli prohlížeči. Když funkce funguje podle očekávání, je připravena přidat do úlohy Stream Analytics a spustit ji přímo z vašeho dotazu. Logiku dotazů můžete také otestovat pomocí JavaScript UDF pomocí nástrojů Stream Analytics pro Visual Studio.

Stream Analytics považuje chyby v běhu JavaScriptu za fatální a zobrazuje je prostřednictvím logu aktivit. Log je dostupný v Azure portálu na stránce Activity log vaší práce.

Volání uživatelem definované funkce jazyka JavaScript v dotazu

Pro vyvolání JavaScriptové funkce ve vašem dotazu použijte alias funkce s předponou udf. Následující příklad ukazuje JavaScript UDF, který převádí hexadecimální hodnoty na celé číslo v dotazu Stream Analytics.

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

Podporované objekty jazyka JavaScript

Uživatelsky definované funkce Azure Stream Analytics JavaScript podporují standardní, vestavěné JavaScript objekty. Tyto objekty umožňují vašim funkcím přístup k běžným řetězcům, matematickým, polovým a datovým operacím bez jakékoli další konfigurace. Pro úplný seznam dostupných objektů viz Globální objekty. Protože dotazovací jazyk Stream Analytics a JavaScript nesdílejí stejný typový systém, Stream Analytics převádí hodnoty při jejich přechodu.

Převod typů v JavaScriptu a Stream Analytics

Dotazovací jazyk Stream Analytics a JavaScript podporují různé typy. Tato tabulka uvádí mapování převodu mezi těmito dvěma jazyky:

Stream Analytics	JavaScript
bigint	Číslo (JavaScript může používat celá čísla jenom do hodnoty 2^53)
DateTime	Datum (JavaScript podporuje jenom milisekundy)
double	Číslo
nvarchar(MAX)	String
Záznam	Objekt
Pole	Pole
NULL	Null

Převody z jazyka JavaScript do Stream Analytics:

JavaScript	Stream Analytics
Číslo	Bigint (pokud je číslo zaokrouhlené a je v rozsahu long.MinValue a long.MaxValue; jinak typ double)
Datum	DateTime
String	nvarchar(MAX)
Objekt	Zaznamenat
Pole	Pole
Null, Nedefinováno	NULL
Jakýkoli jiný typ (například funkce nebo chyba)	Není podporováno (výsledkem je chyba při běhu)

JavaScript rozlišuje velká a malá písmena a způsob psaní názvů polí objektu v kódu JavaScriptu musí odpovídat způsobu psaní názvů polí v příchozích datech. Úlohy s úrovní kompatibility 1.0 převádějí pole ze SQL příkazu SELECT na malá písmena. Na úrovni kompatibility 1.1 a vyšší mají pole ze příkazu SELECT stejné otiskové označení, jaké je specifikováno v SQL dotazu.

Běžné funkční vzory

Následující vzorce ukazují běžné způsoby, jak používat uživatelsky definované funkce v JavaScriptu k transformaci dat ve vašich dotazech Stream Analytics. Každý vzor obsahuje definici funkce a ukázkový dotaz, který jej vyvolá.

Zápis vnořeného řetězce JSON do výstupu

Pokud máte krok následného zpracování, který jako vstup používá výstup úlohy Stream Analytics a vyžaduje formát JSON, můžete do výstupu zapsat řetězec JSON. Následující definice funkce volá funkci JSON.stringify(), která zabalí všechny dvojice jméno/hodnota vstupu a poté je zapíše jako jednu hodnotu řetězce na výstupu.

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

Dotaz Stream Analytics vyvolá funkci, jak je ukázáno v následujícím příkladu.

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

Přetypovat řetězec na objekt JSON ke zpracování

Pokud máte stringové pole, které je JSON, a chcete ho převést na JSON objekt pro zpracování v JavaScript UDF, můžete použít funkci JSON.parse() k vytvoření JSON objektu, který pak můžete použít. Následující definice funkce rozpracuje řetězec a vrátí vlastnost z výsledného objektu.

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

Dotaz Stream Analytics vyvolá funkci, jak je ukázáno v následujícím příkladu.

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

Použití příkazu try/catch pro zpracování chyb

Bloky try/catch vám mohou pomoci identifikovat problémy s nesprávně zformovanými vstupními daty, která předáváte do JavaScriptového UDF. Následující definice funkce používá blok try/catch pro zpracování chyb při parsování.

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

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

V následujícím ukázkovém dotazu předáte celý záznam jako první parametr, aby ho funkce mohla vrátit, pokud dojde k chybě.

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

toLocaleString()

Metoda toLocaleString v JavaScriptu vrací jazykově citlivý řetězec, který reprezentuje data dat-čas z místa, kde metodu voláte. I když Azure Stream Analytics přijímá jako časové razítko pouze UTC jako časové razítko systému, můžete touto metodou převést časové razítko systému na jinou lokalitu a časové pásmo. Tato metoda se chová stejným způsobem jako ta dostupná v Internet Explorer. Následující definice funkce převádí vstupní datum a čas do národního prostředí de-DE.

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

V následujícím vzorkovém dotazu je jako vstupní hodnota předán datetime.

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

Výstupem tohoto dotazu je vstupní datum a čas ve formátu de-DE se zadanými možnostmi.

Samstag, 28. December 2019

Zaznamenávání uživatelských akcí

Logování je mechanismus, který Azure Stream Analytics používá k zachycení vlastních informací z uživatelsky definované funkce v JavaScriptu během běhu úlohy. Protože běžící úloha je jinak neprůhledná, data z logů vám dávají přehled o chování a správnosti vašeho vlastního kódu v reálném čase. Každá protokolová zpráva má přiřazenou úroveň události, která určuje, jak významná zpráva je a zda úloha může dál běžet.

Informační zprávy pocházejí z metody console.info(), například console.info('my info message');. Tato úroveň zaznamenává obecné informace během provádění a nepřerušuje výpočty. Varovné zprávy pocházejí z metody console.warn(), například console.warn('my warning message');. Tato úroveň zaznamenává data, která mohou být nečekaná, ale stále jsou vhodná pro výpočty, takže úloha pokračuje v běhu. Chybové hlášky pocházejí z metod console.error() a console.log(), například console.error('my error message');. Tyto metody se používají pouze v případech, kdy kód nemůže pokračovat, takže vyhodí výjimku s poskytnutými chybovými informacemi a zastaví úkol.

Ke zprávám protokolu můžete přistupovat prostřednictvím diagnostických protokolů.

atob() a btoa()

Stream Analytics podporuje dvě metody konverze do Base64, což je běžný způsob kódování binárních dat jako textu. Metoda btoa() kóduje ASCII řetězec do Base64 a metoda atob() dekóduje řetězec dat kódovaných v Base64 zpět do ASCII řetězce. V následujícím příkladu zakóduje btoa() ASCII řetězec a atob() poté výsledek dekóduje zpět do původního řetězce.

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

Související obsah

• Strojové učení UDF
• C# uživatelsky definované funkce