Funciones definidas por el usuario de JavaScript en Azure Stream Analytics

Azure Stream Analytics admite funciones definidas por el usuario escritas en JavaScript. Utilizando el amplio conjunto de métodos String, RegExp, Math, Array y Date que proporciona JavaScript, puedes crear transformaciones complejas de datos en trabajos de Stream Analytics. Las funciones definidas por el usuario en JavaScript admiten funciones escalares de solo cálculo y sin estado, que no requieren conectividad externa. El valor devuelto de una función solo puede ser un valor escalar (único). Después de agregar una función definida por el usuario en JavaScript a un trabajo, puede usar la función en cualquier parte de la consulta, como una función escalar integrada.

Este artículo describe cuándo usar funciones definidas por el usuario en JavaScript y cómo definirlas y llamarlas en tus trabajos de Stream Analytics.

Cuándo usar una función definida por el usuario en JavaScript

Estos son algunos escenarios en los que le podrían resultar útiles las funciones definidas por el usuario en JavaScript:

• Analizar y manipular cadenas usando funciones de expresión regular, por ejemplo, Regexp_Replace() y Regexp_Extract()
• Descodificación y codificación de datos, por ejemplo, conversión de binario a hexadecimal
• Realizar cálculos matemáticos usando funciones matemáticas en JavaScript
• Realización de operaciones de matriz como ordenar, combinar, buscar y rellenar

Aquí tienes algunas cosas que no puedes hacer usando una función definida por el usuario de JavaScript en Stream Analytics:

• Llama a extremos REST externos, por ejemplo, haciendo búsqueda inversa de IP o extrayendo datos de referencia de una fuente externa
• Realice la serialización o deserialización de un formato personalizado de eventos en las entradas o salidas
• Crear agregados personalizados

Aunque funciones como Date.GetDate() o Math.random() no están bloqueadas en la definición de funciones, evita usarlas. Estas funciones no devuelven el mismo resultado cada vez que las llama y el servicio Azure Stream Analytics no mantiene un diario de las llamadas a funciones y los resultados devueltos. Si una función devuelve un resultado diferente en los mismos eventos, la repetibilidad no está garantizada cuando tú o el servicio de Stream Analytics reiniciáis el trabajo.

Define una función definida por el usuario en JavaScript en el portal de Azure

Para un trabajo de Stream Analytics que se ejecute en la nube, añade una función definida por el usuario en JavaScript desde la página de Funciones bajo Topología de Trabajos, donde el menú +Add incluye una opción UDF de JavaScript .

Nota:

Esta experiencia se aplica a trabajos de Stream Analytics configurados para ejecutarse en la nube. Si el trabajo de Stream Analytics está configurado para ejecutarse en Azure IoT Edge, use entonces Visual Studio y escriba la función definida por el usuario mediante C# .

Una definición de función consiste en las siguientes propiedades:

Propiedad	Descripción
Alias de función	El nombre que invoca la función en tu consulta.
Tipo de salida	El tipo que la función de JavaScript definida por el usuario devuelve a la consulta de Stream Analytics.
Definición de función	La implementación de tu función JavaScript que se ejecuta cada vez que se invoca la UDF desde tu consulta.

Prueba y soluciona problemas con la lógica UDF de JavaScript

Como el portal de Stream Analytics no permite depurar ni probar la lógica de estas funciones definidas por el usuario, puedes probar y depurar la lógica de tu UDF en JavaScript en cualquier navegador. Cuando la función funciona como se espera, está lista para añadirse al trabajo de Stream Analytics e invocar directamente desde tu consulta. También puedes probar tu lógica de consulta con un UDF de JavaScript usando las herramientas de Stream Analytics para Visual Studio.

Stream Analytics trata los errores de ejecución de JavaScript como fatales y los muestra a través del registro de actividad. El registro está disponible en el portal de Azure desde la página de registro de actividad de tu trabajo.

Llamada a una función definida por el usuario de JavaScript en una consulta

Para invocar tu función JavaScript en tu consulta, usa el alias de función prefijado con udf. El siguiente ejemplo muestra un UDF de JavaScript que convierte valores hexadecimales en un entero en una consulta de Stream Analytics.

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

Objetos de JavaScript compatibles

Las funciones definidas por el usuario en JavaScript de Azure Stream Analytics soportan los objetos JavaScript estándar integrados. Estos objetos dan a tus funciones acceso a operaciones comunes de cadenas, matemáticas, arrays y fechas sin ninguna configuración adicional. Para una lista completa de los objetos disponibles, véase Objetos Globales. Como el lenguaje de consulta de Stream Analytics y JavaScript no comparten el mismo sistema de tipos, Stream Analytics convierte los valores a medida que pasan entre ambos.

Conversión de tipos en Stream Analytics y JavaScript

El lenguaje de consulta Stream Analytics y JavaScript soportan diferentes tipos. Esta tabla lista las correspondencias de conversión entre ambos:

Stream Analytics	JavaScript
bigint	Number (JavaScript solamente puede representar enteros hasta 2^53 con precisión)
Fecha y hora	Date (JavaScript solo admite milisegundos)
doble	Número
nvarchar(MAX)	Cadena
Registro	Objeto
Array	Array
NULL	Null

Estas son las conversiones de JavaScript a Stream Analytics:

JavaScript	Stream Analytics
Número	Bigint (si el número es entero y está entre long.MinValue y long.MaxValue; en caso contrario, es double)
Fecha	Fecha y hora
Cadena	nvarchar(MAX)
Objeto	Registro
Array	Array
Null, sin definir	NULL
Cualquier otro tipo (por ejemplo, una función o un error)	No admitido (da lugar a un error en tiempo de ejecución)

JavaScript distingue entre mayúsculas y minúsculas, y el uso de mayúsculas y minúsculas en los campos del objeto del código JavaScript debe coincidir con el de los campos de los datos de entrada. Los trabajos con nivel de compatibilidad 1.0 convierten los campos de la instrucción SELECT de SQL en minúsculas. Con el nivel de compatibilidad 1.1 o superior, los campos de la instrucción SELECT tienen la misma combinación de mayúsculas y minúsculas que la especificada en la consulta SQL.

Patrones de funciones comunes

Los siguientes patrones muestran formas comunes de usar funciones definidas por el usuario en JavaScript para transformar datos en tus consultas de Stream Analytics. Cada patrón incluye una definición de función y una consulta de muestra que la invoca.

Escribir JSON anidado en la salida

Si tiene un paso de procesamiento de seguimiento que usa la salida del trabajo de Stream Analytics como entrada y requiere un formato JSON, puede escribir una cadena JSON en la salida. La siguiente definición de función llama a la función JSON.stringify() para empaquetar todos los pares nombre/valor de la entrada y luego escribirlos como un solo valor de cadena en la salida.

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

Una consulta de Análisis de Flujos invoca la función como se muestra en el siguiente ejemplo.

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

Conversión de una cadena en un objeto JSON para procesar

Si tienes un campo de cadena que es JSON y quieres convertirlo a un objeto JSON para procesarlo en un UDF de JavaScript, puedes usar la función JSON.parse() para crear un objeto JSON que luego puedas usar. La siguiente definición de función analiza la cadena y devuelve una propiedad del objeto resultante.

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

Una consulta de Análisis de Flujos invoca la función como se muestra en el siguiente ejemplo.

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

Uso de try/catch para el control de errores

Los bloques try/catch pueden ayudarte a identificar problemas con datos de entrada deformados que pasas a un UDF de JavaScript. La siguiente definición de función utiliza un bloque try/catch para manejar errores de análisis sintáctico.

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

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

En la siguiente consulta de ejemplo, pasas todo el registro como primer parámetro para que la función pueda devolverlo si hay un error.

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

toLocaleString()

El método toLocaleString en JavaScript devuelve una cadena sensible al lenguaje que representa los datos de fecha-hora desde donde llamas al método. Aunque Azure Stream Analytics solo acepta UTC fecha-hora como marca de tiempo del sistema, puedes usar este método para convertir la marca de tiempo del sistema a otra localidad y zona horaria. Este método sigue el mismo comportamiento de implementación que el disponible en Internet Explorer. La siguiente definición de función convierte la fecha y hora de entrada a la de-DE localidad.

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

En la siguiente consulta de ejemplo, se pasa una fecha y hora como valor de entrada.

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

La salida de esta consulta es la fecha y hora de entrada en de-DE con las opciones proporcionadas.

Samstag, 28. December 2019

Registro de usuarios

El registro es el mecanismo que utiliza Azure Stream Analytics para capturar información personalizada de una función definida por el usuario en JavaScript mientras se ejecuta un trabajo. Dado que un proceso en ejecución sería opaco de otro modo, los registros te permiten ver en tiempo real el comportamiento y el correcto funcionamiento de tu código personalizado. Cada mensaje de registro lleva un nivel de evento que indica cuán significativo es el mensaje y si el trabajo puede seguir ejecutándose.

Los mensajes informativos provienen del método console.info(), como console.info('my info message');. Este nivel registra información general durante la ejecución y no interrumpe el cálculo. Los mensajes de advertencia provienen del método console.warn(), como console.warn('my warning message');. Este nivel registra datos que pueden ser inesperados pero que aún son aceptables para el cálculo, por lo que el trabajo continúa ejecutándose. Los mensajes de error provienen de los métodos console.error() y console.log(), como console.error('my error message');. Estos métodos solo se aplican en casos en los que el código no puede continuar, por lo que lanzan una excepción con la información de error proporcionada y detienen el trabajo.

Puede acceder a los mensajes de registro a través de los registros de diagnóstico.

atob() y btoa()

Stream Analytics soporta dos métodos para la conversión a Base64, que es una forma común de codificar datos binarios como texto. El método btoa() codifica una cadena ASCII en Base64, y el método atob() decodifica una cadena de datos codificados en Base64 en una cadena ASCII. En el siguiente ejemplo, btoa() codifica una cadena ASCII y atob() luego decodifica el resultado de nuevo en la cadena original.

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

Contenido relacionado

• UDF de aprendizaje automático
• Funciones definidas por el usuario en C#