Funzioni JavaScript definite dall'utente in Analisi di flusso di AzureAzure Stream Analytics JavaScript user-defined functions

L'Analisi di flusso di Azure supporta le funzioni definite dall'utente nel linguaggio JavaScript.Azure Stream Analytics supports user-defined functions written in 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.With the rich set of String, RegExp, Math, Array, and Date methods that JavaScript provides, complex data transformations with Stream Analytics jobs become easier to create.

Funzioni JavaScript definite dall'utenteJavaScript user-defined functions

Le funzioni JavaScript definite dall'utente supportano funzioni senza stato e di solo calcolo che non richiedono connettività esterna.JavaScript user-defined functions support stateless, compute-only scalar functions that do not require external connectivity. Il valore restituito di una funzione può essere solo un valore scalare singolo.The return value of a function can only be a scalar (single) value. 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.After you add a JavaScript user-defined function to a job, you can use the function anywhere in the query, like a built-in scalar function.

Ecco alcuni scenari in cui potrebbero essere utili le funzioni JavaScript definite dall'utente:Here are some scenarios where you might find JavaScript user-defined functions useful:

  • Analisi e manipolazione delle stringhe con funzioni di espressione regolare, ad esempio Regexp_Replace() e Regexp_Extract()Parsing and manipulating strings that have regular expression functions, for example, Regexp_Replace() and Regexp_Extract()
  • Decodifica e codifica dati, ad esempio conversione dal formato binario al formato esadecimaleDecoding and encoding data, for example, binary-to-hex conversion
  • Esecuzione di calcoli matematici con funzioni JavaScript MathPerforming mathematic computations with JavaScript Math functions
  • Esecuzione di operazioni di matrice come ordinamento, aggiunta, ricerca e riempimentoPerforming array operations like sort, join, find, and fill

Ecco alcune operazioni non eseguibili con una funzione JavaScript definita dall'utente in Analisi di flusso:Here are some things that you cannot do with a JavaScript user-defined function in Stream Analytics:

  • 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 esternaCall out external REST endpoints, for example, performing reverse IP lookup or pulling reference data from an external source
  • Esecuzione della serializzazione o deserializzazione negli input e output di un formato evento personalizzatoPerform custom event format serialization or deserialization on inputs/outputs
  • Creazione di aggregazioni personalizzateCreate custom aggregates

Sebbene le funzioni come Date.GetDate() o Math.random() non sono bloccate nella definizione delle funzioni, è consigliabile evitare di utilizzarle.Although functions like Date.GetDate() or Math.random() are not blocked in the functions definition, you should avoid using them. Queste funzioni, infatti, non restituiscono lo stesso risultato ogni volta che vengono chiamate e Analisi di flusso di Azure non conserva un giornale di chiamate di funzione e dei risultati restituiti.These functions do not return the same result every time you call them, and the Azure Stream Analytics service does not keep a journal of function invocations and returned results. 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.If a function returns different result on the same events, repeatability is not guaranteed when a job is restarted by you or by the Stream Analytics service.

Aggiungere una funzione JavaScript definita dall'utente nel portale di AzureAdd a JavaScript user-defined function in the Azure portal

I passaggi seguenti illustrano come creare una semplice funzione JavaScript definita dall'utente in un processo esistente di Analisi di flusso:To create a simple JavaScript user-defined function under an existing Stream Analytics job, do these steps:

  1. Nel portale di Azure individuare il processo di Analisi di flusso.In the Azure portal, find your Stream Analytics job.
  2. In TOPOLOGIA PROCESSO selezionare la funzione.Under JOB TOPOLOGY, select your function. Viene visualizzato un elenco vuoto di funzioni.An empty list of functions appears.
  3. Per creare una nuova funzione definita dall'utente, selezionare Aggiungi.To create a new user-defined function, select Add.
  4. Sul pannello Nuova funzione selezionare JavaScript per Tipo funzione.On the New Function blade, for Function Type, select JavaScript. Nell'editor viene visualizzato un modello di funzione predefinita.A default function template appears in the editor.
  5. Per l'alias della funzione definita dall'utente, inserire hex2Int e modificare l'implementazione della funzione come indicato di seguito:For the UDF alias, enter hex2Int, and change the function implementation as follows:

    // Convert Hex value to integer.
    function main(hexValue) {
        return parseInt(hexValue, 16);
    }
    
  6. Selezionare Salva.Select Save. La funzione viene visualizzata nell'elenco delle funzioni.Your function appears in the list of functions.

  7. Selezionare la nuova funzione hex2Int e controllare la definizione di funzione.Select the new hex2Int function, and check the function definition. Per ogni funzione, all'alias della funzione viene aggiunto un prefisso della funzione definita dall'utente.All functions have a UDF prefix added to the function alias. È necessario includere il prefisso quando si chiama la funzione nella query Analisi di flusso.You need to include the prefix when you call the function in your Stream Analytics query. In questo caso, si chiama UDF.hex2Int.In this case, you call UDF.hex2Int.

Chiamare una funzione JavaScript definita dall'utente nella queryCall a JavaScript user-defined function in a query

  1. Nell'editor di query, in TOPOLOGIA PROCESSO, selezionare Query.In the query editor, under JOB TOPOLOGY, select Query.
  2. Modificare la query e quindi chiamare la funzione definita dall'utente, simile alla seguente:Edit your query, and then call the user-defined function, like this:

    SELECT
        time,
        UDF.hex2Int(offset) AS IntOffset
    INTO
        output
    FROM
        InputStream
    
  3. Per caricare un file di dati di esempio, fare clic con il tasto destro del mouse sull'input del processo.To upload the sample data file, right-click the job input.

  4. Per testare la query, selezionare Test.To test your query, select Test.

Oggetti JavaScript supportatiSupported JavaScript objects

Le funzioni JavaScript definite dall'utente in Analisi di flusso di Azure supportano oggetti JavaScript standard e incorporati.Azure Stream Analytics JavaScript user-defined functions support standard, built-in JavaScript objects. Per un elenco di questi oggetti, vedere Oggetti globali.For a list of these objects, see Global Objects.

Conversione dei tipi di Analisi di flusso e JavaScriptStream Analytics and JavaScript type conversion

Esistono delle differenze tra i tipi supportati da JavaScript e dal linguaggio di query di Analisi di flusso.There are differences in the types that the Stream Analytics query language and JavaScript support. Questa tabella elenca i mapping di conversione tra i due:This table lists the conversion mappings between the two:

Analisi dei flussiStream Analytics JavaScriptJavaScript
bigintbigint Numero (per la precisione, JavaScript può rappresentare solo numeri interi fino a 2^53)Number (JavaScript can only represent integers up to precisely 2^53)
DateTimeDateTime Data (JavaScript supporta solo millisecondi)Date (JavaScript only supports milliseconds)
doubledouble NumberNumber
nvarchar(MAX)nvarchar(MAX) stringString
RecordRecord OggettoObject
ArrayArray ArrayArray
NULLNULL NullNull

Ecco le conversioni da JavaScript ad Analisi di flusso:Here are JavaScript-to-Stream Analytics conversions:

JavaScriptJavaScript Analisi dei flussiStream Analytics
NumberNumber Bigint (se il numero è arrotondato e compreso tra long.MinValue e long.MaxValue, in caso contrario è doppio)Bigint (if the number is round and between long.MinValue and long.MaxValue; otherwise, it's double)
DateDate DateTimeDateTime
StringString nvarchar(MAX)nvarchar(MAX)
OggettoObject RecordRecord
ArrayArray ArrayArray
Null, UndefinedNull, Undefined NULLNULL
Qualsiasi altro tipo (ad esempio, una funzione o un errore)Any other type (for example, a function or error) Non supportato (risultati nell'errore di runtime)Not supported (results in runtime error)

Risoluzione dei problemiTroubleshooting

Gli errori di runtime in JavaScript sono considerati irreversibili ed esposti tramite il log attività.JavaScript runtime errors are considered fatal, and are surfaced through the Activity log. Per recuperare il log, nel portale di Azure passare al processo e selezionare Log attività.To retrieve the log, in the Azure portal, go to your job and select Activity log.

Altri modelli della funzione JavaScript definita dall'utenteOther JavaScript user-defined function patterns

Scrivere una stringa JSON nidificata in outputWrite nested JSON to 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.If you have a follow-up processing step that uses a Stream Analytics job output as input, and it requires a JSON format, you can write a JSON string to 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.The next example calls the JSON.stringify() function to pack all name/value pairs of the input, and then write them as a single string value in output.

Definizione della funzione JavaScript definita dall'utente:JavaScript user-defined function definition:

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

Query di esempio:Sample query:

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

Ottenere aiutoGet help

Per ulteriore assistenza, provare il Forum di Analisi di flusso di Azure.For additional help, try our Azure Stream Analytics forum.

Passaggi successiviNext steps