Funzioni JavaScript definite dall'utente in Analisi di flusso di Azure

L'Analisi di flusso di Azure supporta le funzioni definite dall'utente nel linguaggio JavaScript. Utilizzando il ricco set di metodi String, RegExp, Math, Array e Date forniti da JavaScript, puoi creare trasformazioni di dati complesse nei job di Stream Analytics. Le funzioni JavaScript definite dall'utente supportano funzioni scalari di solo calcolo senza stato che non richiedono connettività esterna. Il valore restituito di una funzione può essere solo un valore scalare singolo. Dopo aver aggiunto una funzione JavaScript definita dall'utente a un processo, è possibile utilizzare la funzione in un punto qualsiasi nella query, ad esempio una funzione scalare incorporata.

Questo articolo descrive quando utilizzare funzioni definite dall'utente in JavaScript e come definirle e chiamarle nei tuoi lavori di Stream Analytics.

Quando utilizzare una funzione definita dall'utente in JavaScript

Ecco alcuni scenari in cui potrebbero essere utili le funzioni JavaScript definite dall'utente:

• Parsing e manipolazione delle stringhe usando funzioni di espressione regolare, ad esempio Regexp_Replace() e Regexp_Extract()
• Decodifica e codifica dati, ad esempio conversione dal formato binario al formato esadecimale
• Eseguire calcoli matematici utilizzando funzioni matematiche in JavaScript
• Esecuzione di operazioni di matrice come ordinamento, aggiunta, ricerca e riempimento

Ecco alcune cose che non puoi fare usando una funzione definita dall'utente in JavaScript in Stream Analytics:

• Chiama endpoint REST esterni, ad esempio, effettuando ricerca IP inversa o estraendo dati di riferimento da una sorgente esterna
• Eseguire la serializzazione o la deserializzazione del formato di evento personalizzato sugli input o sugli output
• Creazione di aggregazioni personalizzate

Anche se funzioni come Date.GetDate() o Math.random() non sono bloccate nella definizione delle funzioni, evita di usarle. Queste funzioni, infatti, non restituiscono lo stesso risultato ogni volta che vengono chiamate e Analisi di flusso di Azure non conserva un giornale di registrazione delle chiamate di funzione e dei risultati restituiti. Se una funzione restituisce un risultato diverso sugli stessi eventi, la ripetibilità non è garantita quando tu o il servizio Stream Analytics riavviate il lavoro.

Definisci una funzione definita dall'utente in JavaScript nel portale Azure

Per un lavoro di Stream Analytics che gira nel cloud, aggiungi una funzione definita dall'utente in JavaScript dalla pagina Funzioni sotto Topologia del lavoro, dove il menu +Add include un'opzione UDF JavaScript .

Una definizione di funzione consiste nelle seguenti proprietà:

Testare e risolvere problemi della logica UDF di JavaScript

Poiché il portale Stream Analytics non supporta il debug e il test della logica di queste funzioni definite dall'utente, puoi testare e debugare la logica UDF JavaScript in qualsiasi browser. Quando la funzione funziona come previsto, è pronta per essere aggiunta al lavoro di Stream Analytics e invocata direttamente dalla tua query. Puoi anche testare la logica delle query con un UDF JavaScript utilizzando gli strumenti Stream Analytics per Visual Studio.

Stream Analytics considera gli errori di esecuzione di JavaScript fatali e li mostra attraverso il registro delle attività. Il registro è disponibile nel portale Azure dalla pagina del registro attività del tuo lavoro.

Chiamare una funzione JavaScript definita dall'utente nella query

Per richiamare la funzione JavaScript nella query, usa l'alias della funzione preceduto da udf. Il seguente esempio mostra un UDF JavaScript che converte i valori esadecimali in un intero in una query Stream Analytics.

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

Oggetti JavaScript supportati

Analisi di flusso di Azure Le funzioni definite dall'utente in JavaScript supportano gli oggetti JavaScript standard integrati. Questi oggetti danno alle tue funzioni accesso a operazioni comuni di stringhe, matematiche, array e date senza alcuna configurazione aggiuntiva. Per un elenco completo degli oggetti disponibili, vedi Oggetti Globali. Poiché il linguaggio di query di Stream Analytics e JavaScript non condividono lo stesso sistema di tipi, Stream Analytics converte i valori man mano che passano tra i due.

Conversione dei tipi di Analisi di flusso e JavaScript

Il linguaggio di query Stream Analytics e JavaScript supportano diversi tipi. Questa tabella elenca le mappature di conversione tra i due elementi:

Ecco le conversioni da JavaScript a Stream Analytics:

JavaScript fa distinzione tra maiuscole e minuscole e l'uso di maiuscole e minuscole dei campi dell'oggetto nel codice JavaScript deve corrispondere a quello dei campi presenti nei dati in ingresso. I lavori con livello di compatibilità 1.0 convertono i campi dall'istruzione SQL SELECT in minuscolo. Con il livello di compatibilità 1.1 o superiore, i campi dell'istruzione SELECT presentano la stessa combinazione di maiuscole e minuscole specificata nella query SQL.

Schemi di funzione comuni

I seguenti modelli mostrano modi comuni per utilizzare funzioni definite dall'utente in JavaScript per trasformare i dati nelle tue query Stream Analytics. Ogni modello include una definizione di funzione e una query di esempio che la richiama.

Scrivere JSON annidato nell'output

In caso di passaggi di elaborazione successivi che utilizzano un output di un processo di Analisi di flusso come input e l'output richiede un formato JSON, è possibile scrivere una stringa JSON in output. La seguente definizione di funzione chiama la funzione JSON.stringify() per impacchettare tutte le coppie nome/valore dell'input e poi scriverle come un singolo valore di stringa in output.

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

Una query di Stream Analytics invoca la funzione come mostrato nel seguente esempio.

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

Convertire la stringa in un oggetto JSON da elaborare

Se hai un campo stringa JSON e vuoi convertirlo in un oggetto JSON per l'elaborazione in un UDF JavaScript, puoi usare la funzione JSON.parse() per creare un oggetto JSON che poi puoi utilizzare. La seguente definizione di funzione analizza la stringa e restituisce una proprietà dall'oggetto risultante.

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

Una query di Stream Analytics invoca la funzione come mostrato nel seguente esempio.

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

usare try/catch per la gestione degli errori

I blocchi try/catch possono aiutarti a identificare problemi con dati di input malformati che passi in un UDF JavaScript. La seguente definizione di funzione utilizza un blocco try/catch per gestire gli errori di parsing.

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

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

Nella query di esempio seguente, passi l'intero record come primo parametro così che la funzione possa restituirlo se c'è un errore.

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

toLocaleString()

Il metodo toLocaleString in JavaScript restituisce una stringa sensibile al linguaggio che rappresenta i dati data-ora da cui si chiama il metodo. Anche se Analisi di flusso di Azure accetta solo data-ora UTC come timestamp di sistema, puoi usare questo metodo per convertire il timestamp di sistema in un'altra zona e fuso orario. Questo metodo segue lo stesso comportamento di implementazione di quello disponibile in Internet Explorer. La seguente definizione di funzione converte la data e ora di input nel locale de-DE.

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

Nella seguente query di esempio, viene passato un valore datatime come valore di input.

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

L'output di questa query è la data e ora di input in de-DE con le opzioni fornite.

Samstag, 28. December 2019

Registrazione utente

Il logging è il meccanismo che Analisi di flusso di Azure utilizza per catturare informazioni personalizzate da una funzione definita dall'utente in JavaScript mentre un lavoro è in esecuzione. Poiché un lavoro in esecuzione è altrimenti opaco, i dati di log ti danno visibilità sul comportamento e sulla correttezza del tuo codice personalizzato in tempo reale. Ogni messaggio di log porta un livello di evento che indica quanto sia significativo il messaggio e se il lavoro può continuare a funzionare.

I messaggi informativi provengono dal metodo console.info(), come console.info('my info message');. Questo livello registra le informazioni generali durante l'esecuzione e non interrompe il calcolo. I messaggi di avviso provengono dal metodo console.warn(), come console.warn('my warning message');. Questo livello registra dati che potrebbero essere inaspettati ma comunque accettabili per il calcolo, quindi il lavoro continua a essere eseguito. I messaggi di errore provengono dai metodi console.error() e console.log(), come console.error('my error message');. Questi metodi si applicano solo ai casi in cui il codice non può continuare, quindi lanciano un'eccezione con le informazioni di errore fornite e interrompono il lavoro.

È possibile accedere ai messaggi dei log tramite i log di diagnostica.

atob() e btoa()

Stream Analytics supporta due metodi per la conversione Base64, che è un modo comune per codificare dati binari come testo. Il metodo btoa() codifica una stringa ASCII in Base64, e il metodo atob() decodifica una stringa di dati codificati in Base64 in una stringa ASCII. Nel seguente esempio, btoa() si codifica una stringa ASCII e atob() poi si decodifica il risultato nella stringa originale.

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

Contenuti correlati

• Machine learning UDF
• Funzioni definite dall'utente in C#