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. Con il vasto set di metodi String, RegExp, Math, Array e Date offerti da JavaScript, risulta più facile creare trasformazioni di dati complessi con processi di Analisi di flusso.

Panoramica

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.

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

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

Ecco alcune operazioni non eseguibili con una funzione JavaScript definita dall'utente in Analisi di flusso:

• Chiamate agli endpoint REST esterni, ad esempio per l'esecuzione di una ricerca inversa degli indirizzi IP o per la raccolta di dati di riferimento da un'origine esterna
• Esecuzione della serializzazione o deserializzazione negli input e output di un formato evento personalizzato
• Creazione di aggregazioni personalizzate

Sebbene le funzioni come Date.GetDate() o Math.random() non sono bloccate nella definizione delle funzioni, è consigliabile evitare 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 risultati diversi per gli stessi eventi, non viene garantita la ripetibilità in caso di processo riavviato dall'utente o dal servizio di Analisi di flusso.

Eseguire una funzione JavaScript definita dall'utente al processo

Per creare una funzione JavaScript definita dall'utente nel processo di Analisi di flusso, selezionare Funzioni in Topologia processo. Selezionare quindi UDF JavaScript dal menu a discesa + Aggiungi.

È quindi necessario specificare le proprietà seguenti e selezionare Salva.

Testare e risolvere i problemi delle funzioni definite dall'utente JavaScript

È possibile testare ed eseguire il debug della logica delle funzioni definite dall'utente JavaScript in qualsiasi browser. Il debug e il test della logica di queste funzioni definite dall'utente non sono attualmente supportati nel portale di Analisi di flusso. Quando la funzione si comporta come previsto, è possibile aggiungerla al processo di analisi di flusso come indicato in precedenza e quindi richiamarla direttamente dalla query. È possibile testare la logica di query con la funzione definita dall'utente JavaScript usando gli strumenti di Analisi di flusso di Azure per Visual Studio.

Gli errori di runtime in JavaScript sono considerati irreversibili ed esposti tramite il log attività. Per recuperare il log, nel portale di Azure passare al processo e selezionare Log attività.

Chiamare una funzione JavaScript definita dall'utente nella query

È possibile richiamare facilmente la funzione JavaScript nella query usando l'alias di funzione con il prefisso udf. Di seguito è riportato un esempio di una funzione definita dall'utente JavaScript che converte i valori esadecimali in valori integer richiamati in una query di Analisi di flusso.

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

Oggetti JavaScript supportati

Le funzioni JavaScript definite dall'utente in Analisi di flusso di Azure supportano oggetti JavaScript standard e incorporati. Per un elenco di questi oggetti, vedere Oggetti globali.

Conversione dei tipi di Analisi di flusso e JavaScript

Esistono delle differenze tra i tipi supportati da JavaScript e dal linguaggio di query di Analisi di flusso. Questa tabella elenca i mapping di conversione tra i due:

Ecco le conversioni da JavaScript ad Analisi di flusso:

Il linguaggio JavaScript distingue tra maiuscole/minuscole e le maiuscole e le minuscole dei campi oggetto nel codice JavaScript devono corrispondere alle maiuscole e alle minuscole dei campi nei dati in ingresso. I processi con livello di compatibilità 1.0 convertiranno i campi dall'istruzione SQL SELECT affinché siano minuscoli. Nel livello di compatibilità 1.1 e superiore, i campi dall'istruzione SELECT avranno le stesse maiuscole e minuscole come specificate nella query SQL.

Altri modelli della funzione JavaScript definita dall'utente

Scrivere una stringa JSON nidificata in 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. L'esempio successivo chiama la funzione JSON.stringify() per raccogliere tutte le coppie nome/valore dell'input e quindi scriverle come valore di stringa singola nell'output.

Definizione della funzione JavaScript definita dall'utente:

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

Query di esempio:

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

eseguire il cast della stringa all'oggetto JSON da elaborare

Se è presente un campo stringa JSON e si vuole convertirlo in un oggetto JSON per l'elaborazione in una funzione definita dall'utente JavaScript, è possibile usare la funzione JSON.parse() per creare un oggetto JSON da usare a questo scopo.

Definizione della funzione JavaScript definita dall'utente:

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

Query di esempio:

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

usare try/catch per la gestione degli errori

I blocchi try/catch consentono di identificare i problemi relativi a dati di input in formato non valido passati in una funzione definita dall'utente JavaScript.

Definizione della funzione JavaScript definita dall'utente:

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

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

Query di esempio: passare l'intero record come primo parametro in modo che possa essere restituito se si verifica 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 può essere usato per restituire una stringa sensibile al linguaggio che rappresenta i dati di data/ora relativi al momento in cui il metodo viene chiamato. Anche se Analisi di flusso di Azure accetta solo date e ore in formato UTC come timestamp di sistema, questo metodo può essere usato per convertire il timestamp di sistema in altre impostazioni locali e fusi orari. Questo metodo segue lo stesso comportamento di implementazione di quello disponibile in Internet Explorer.

Definizione della funzione JavaScript definita dall'utente:

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

Query di esempio: Passare una data/ora come valore di input

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

L'output di questa query corrisponde alla data/ora immessa in de-DE con le opzioni specificate.

Samstag, 28. Dezember 2019

Registrazione utenti

Il meccanismo di registrazione consente agli utenti di acquisire informazioni personalizzate durante l'esecuzione di un processo. I dati di log possono essere usati per eseguire il debug o valutare la correttezza del codice personalizzato in tempo reale. Questo meccanismo è disponibile tramite tre diversi metodi.

Console.Info()

Console.Info metodo viene usato per registrare informazioni generali durante l'esecuzione del codice. Questo metodo registra i dati senza interrompere il calcolo. Il messaggio registrato verrà contrassegnato come Informazioni a livello di evento.

console.info('my info message');

Console.Warn()

Il metodo Console.Warn viene usato per registrare i dati che potrebbero non essere corretti o previsti, ma è ancora accettato per il calcolo. Questo metodo non interromperà il calcolo e riprenderà l'esecuzione dopo la restituzione del metodo. Il messaggio registrato verrà contrassegnato come avviso a livello di evento.

console.warn('my warning message');

Console.Error() e Console.Log()

Il metodo Console.Error viene usato solo per registrare i casi di errore in cui il codice non può continuare a essere eseguito. Questo metodo genererà un'eccezione con le informazioni sull'errore fornite come parametro di input e il processo smetterà di eseguire. Il messaggio di errore registrato verrà contrassegnato come errore a livello di evento.

console.error('my error message');

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

atob() e btoa()

Il metodo btoa() può essere usato per codificare una stringa ASCII in Base64. Questa operazione viene in genere eseguita per trasferire i dati in un formato binario. Il metodo atob() può essere usato per decodificare una stringa di dati codificata in Base64 in un formato stringa ASCII.

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

Passaggi successivi

• Funzione definita dall'utente di Machine Learning
• Funzione definita dall'utente in C#