Desarrollar funciones definidas por el usuario de .NET Standard para trabajos de Azure Stream Analytics (Retirado)

Azure Stream Analytics ofrece un lenguaje de consulta similar a SQL para realizar transformaciones y cálculos en secuencias de datos de eventos. El lenguaje incluye muchas funciones integradas, pero algunos escenarios complejos requieren más flexibilidad. Al usar funciones definidas por el usuario (UDF) de .NET Standard, puedes invocar tus propias funciones escritas en cualquier lenguaje .NET Standard (por ejemplo, C# o F#) para extender el lenguaje de consulta de Stream Analytics. Utilizar UDFs para realizar cálculos matemáticos complejos, importar modelos de aprendizaje automático personalizados usando ML.NET y usar lógica de imputación personalizada para los datos perdidos.

Como esta función ha sido retirada, utiliza este artículo para entender cómo funcionaban los UDF estándar .NET y para planificar tu migración a funciones definidas por el usuario en JavaScript.

Acerca de .NET Funciones definidas por el usuario estándar

Los UDFs estándar .NET extienden el lenguaje de consulta de Stream Analytics con lógica personalizada. Antes de crear un UDF, revisa las regiones donde se ejecuta la característica, la ruta del paquete que utiliza, los mapeos de tipos compatibles y las limitaciones de las características.

Azure Stream Analytics permite la característica de funciones definidas por el usuario de .NET para trabajos en la nube que se ejecutan en clústeres de Stream Analytics. Los trabajos que se ejecutan en el SKU multitenant Standard pueden usar esta función en las siguientes regiones públicas:

• Centro-Oeste de EE. UU.
• Norte de Europa
• East US
• Oeste de EE. UU.
• Este de EE. UU. 2
• Oeste de Europa

Para usar esta función en otra región, solicita acceso.

El formato de cualquier paquete UDF tiene la ruta /UserCustomCode/CLR/*. Azure Stream Analytics copia las bibliotecas de enlaces dinámicos (DLLs) y recursos bajo la /UserCustomCode/CLR/* carpeta, lo que ayuda a aislar las DLLs de usuario de las DLLs de sistema y Azure Stream Analytics. Todas las funciones utilizan esta ruta de paquete, independientemente de cómo las emplees.

Para que los valores de Azure Stream Analytics se usen en C#, deben empaquetarse de un entorno a otro. La serialización se produce para todos los parámetros de entrada de una UDF. Cada tipo de Azure Stream Analytics tiene un tipo correspondiente en C#, mostrado en la siguiente tabla:

Lo mismo se aplica cuando es necesario serializar datos de C# a Azure Stream Analytics, lo cual sucede en el valor de salida de una UDF. La siguiente tabla muestra los tipos soportados:

La característica UDF tiene las siguientes limitaciones:

• Puedes crear UDFs estándar .NET solo en Visual Studio Code o Visual Studio, y luego publicarlos en Azure. Puedes ver versiones de solo lectura de los UDFs estándar .NET en Funciones en el portal de Azure. El portal de Azure no permite la creación de funciones estándar .NET.
• El editor de consultas del portal de Azure muestra un error cuando usas un UDF .NET Standard en el portal.
• No puedes llamar a endpoints REST externos, como hacer una búsqueda inversa de IP o extraer datos de referencia de una fuente externa.
• Como el código personalizado comparte contexto con el motor de Azure Stream Analytics, no puede hacer referencia a nada que tenga un espacio de nombres o un nombre de DLL que entre en conflicto con el código de Azure Stream Analytics. Por ejemplo, no puedes referenciar Newtonsoft.Json.
• Azure Stream Analytics copia los archivos de soporte del proyecto al archivo zip de User Custom Code que utiliza cuando publicas el trabajo en la nube. Durante la descompresión, todos los archivos en subcarpetas se trasladan a la raíz de la carpeta de Código Personalizado de Usuario en la nube. La descompresión aplana el archivo zip.
• El código personalizado de usuario no admite carpetas vacías. No agregue carpetas vacías a los archivos auxiliares del proyecto.

Desarrollo de una UDF en Visual Studio Code

Las herramientas de Visual Studio Code para Azure Stream Analytics facilitan la escritura de UDF, probar los trabajos localmente (incluso sin conexión) y publicar el trabajo de Stream Analytics en Azure. Puedes implementar UDFs estándar .NET en Visual Studio Code desde un proyecto local o desde DLLs locales. También puede hacer referencia a archivos DLL locales que incluyan las funciones definidas por el usuario.

Utiliza un proyecto local para funciones complejas que requieren toda la potencia de un lenguaje estándar .NET más allá de su lenguaje de expresión, como lógica procedimental o recursión. Un proyecto local también ayuda cuando necesitas compartir la lógica de funciones entre varias consultas de Azure Stream Analytics, y puedes depurar y probar tus funciones localmente. En el siguiente ejemplo, CSharpUDFProject es un proyecto de biblioteca de clase C#, y ASAUDFDemo es el proyecto Azure Stream Analytics, que hace referencia a CSharpUDFProject.

1. Crea una nueva biblioteca de clases .NET Standard en tu máquina local.

   

2. Escriba el código en la clase . Define las clases como públicas y los objetos como públicos estáticos. La siguiente UDF multiplica un entero por sí misma para producir el cuadrado del entero.

   using System;
   
   namespace CSharpUDFProject
   {
      //
       public class Class1
       {
           public static Int64 SquareFunction(Int64 a)
           {
               return a * a;
           }
       }
   }
   

3. Añade un nuevo archivo de configuración de función C# en tu proyecto de Azure Stream Analytics y haz referencia al proyecto de la biblioteca de clases C#. Para añadir la función, selecciona y mantén pulsado (o haz clic derecho) en la carpeta Functions , y luego elige Añadir elemento.

   

4. Agregue una función de C# SquareFunction al proyecto de Azure Stream Analytics.

   

5. Introduce el nombre de la función C#.

   

6. En la configuración de la función C#, selecciona Elegir ruta de proyecto de biblioteca para elegir tu proyecto C# en la lista desplegable, y selecciona Construir proyecto para construir tu proyecto. A continuación, elija Seleccionar clase y Seleccionar método para seleccionar la clase y el nombre del método relacionados en la lista desplegable. Para referirse a los métodos, tipos y funciones en la consulta de Stream Analytics, define las clases como públicas y los objetos como públicos estáticos.

   

7. Para usar el UDF de C# desde un DLL, selecciona Elegir ruta DLL de biblioteca para elegir el DLL, luego selecciona la clase Select y el método Select.

   

8. Invoque la UDF en la consulta de Azure Stream Analytics.

    SELECT price, udf.SquareFunction(price)
    INTO Output
    FROM Input 
   

9. Configura la ruta del ensamblado en el archivo de configuración del trabajo JobConfig.json, en la sección CustomCodeStorage. Este paso no es necesario para las pruebas locales.

10. Antes de enviar el trabajo a Azure, configura la ruta del paquete en el JobConfig.json archivo de configuración del trabajo, en la sección CustomCodeStorage. Utiliza Seleccionar en tu suscripción en CodeLens para elegir tu suscripción y, en la lista desplegable, elige la cuenta de almacenamiento y el nombre del contenedor. Deje Ruta de acceso como predeterminada. Este paso no es necesario para las pruebas locales.

    

Desarrollo de una UDF en Visual Studio

Puedes implementar UDFs en Visual Studio usando archivos CodeBehind en un proyecto ASA, un UDF de un proyecto local o un paquete existente desde una cuenta de almacenamiento de Azure. En el siguiente ejemplo, UDFTest es un proyecto de biblioteca de clases C#, y ASAUDFDemo es el proyecto Azure Stream Analytics, que hace referencia a UDFTest.

Para la opción CodeBehind, escribe funciones definidas por el usuario en el archivo CodeBehind Script.asql . Las herramientas de Visual Studio compilan automáticamente el archivo CodeBehind en un archivo ensamblador. Las herramientas empaquetan los ensamblajes como un archivo zip y los suben a tu cuenta de almacenamiento cuando envías tu trabajo a Azure. Para aprender a escribir una UDF en C# mediante CodeBehind, sigue el tutorial UDF de C# para trabajos de Edge de Stream Analytics.

1. Crea una nueva biblioteca de clases .NET Standard en tu solución.

   

2. Escriba el código en la clase . Define las clases como públicas y los objetos como públicos estáticos.

3. Construye tu proyecto. Las herramientas empaquetan todos los artefactos de la carpeta bin en un archivo zip y suben el archivo zip a la cuenta de almacenamiento. Para referencias externas, utiliza una referencia de ensamblador en lugar del paquete NuGet.

4. Haga referencia a la nueva clase en el proyecto de Azure Stream Analytics.

5. Agregue una nueva función en el proyecto de Azure Stream Analytics.

6. Configure la ruta del ensamblado en el archivo de configuración del trabajo JobConfig.json. Establece la ruta de ensamblador como Local Project Reference o CodeBehind.

7. Vuelva a generar el proyecto de función y el proyecto de Azure Stream Analytics.

8. Construye tu proyecto en C# para poder añadir una referencia a tu UDF de C# desde la consulta de Azure Stream Analytics.

   

9. Agregue la referencia al proyecto de C# en el proyecto de ASA. Selecciona y mantén pulsado (o haz clic derecho) en el nodo Referencias , y luego elige Añadir Referencia.

   

10. Elija el nombre del proyecto de C# de la lista.

    

11. Confirma que UDFTest aparece en Referencias en Explorador de soluciones.

    

12. Selecciona y mantén pulsado (o haz clic derecho) en la carpeta Functions , y luego elige Nuevo Elemento.

    

13. Agregue una función de C# SquareFunction.json al proyecto de Azure Stream Analytics.

    

14. Abre la función en el Explorador de soluciones para mostrar el diálogo de configuración.

    

15. En la configuración de la función de C#, elija Cargar de la referencia de proyecto de ASA y los nombres de método, la clase y el ensamblado relacionados en la lista desplegable. Para referirse a los métodos, tipos y funciones en la consulta de Stream Analytics, define las clases como públicas y los objetos como públicos estáticos.

    

Configurar los paquetes UDF estándar .NET existentes

Puedes crear UDFs .NET Standard en cualquier IDE e invocarlos desde tu consulta de Azure Stream Analytics. Después de subir los paquetes assembly zip a tu cuenta de almacenamiento de Azure, puedes usar las funciones de las consultas de Azure Stream Analytics incluyendo la información de almacenamiento en la configuración del trabajo de Stream Analytics. No puedes probar la función localmente con esta opción porque las herramientas de Visual Studio no descargan tu paquete. El servicio analiza directamente la ruta del paquete. Para usar un paquete existente:

1. Compila tu código y empaqueta todas las DLLs usando la ruta /UserCustomCode/CLR/*.

2. Súbela UserCustomCode.zip a la raíz del contenedor en tu cuenta de almacenamiento de Azure.

3. En el archivo de configuración del trabajo JobConfig.json, amplía la sección Configuración del código definido por el usuario.

4. Rellena la configuración con los siguientes valores sugeridos.

   Setting	Valor sugerido
   Recurso de configuración de almacenamiento global	Elija el origen de datos de la cuenta actual
   Suscripción a la configuración global de almacenamiento	< su suscripción >
   Configuraciones Globales de Almacenamiento Cuenta de Almacenamiento	< su cuenta de almacenamiento >
   Recurso de configuración de almacenamiento para código personalizado	Elija el origen de datos de la cuenta actual
   Cuenta de almacenamiento de configuración de almacenamiento de código personalizado	< su cuenta de almacenamiento >
   Contenedor de configuración de almacenamiento de código personalizado	< su contenedor de almacenamiento >
   Origen del ensamblado de código personalizado	Paquetes de ensamblado existentes desde la nube
   Origen del ensamblado de código personalizado	UserCustomCode.zip

Registrar información personalizada con la clase StreamingContext

Utilizando el mecanismo de registro, puedes capturar información personalizada mientras se ejecuta un trabajo. Utiliza los datos de registro para depurar o evaluar la corrección del código personalizado en tiempo real. Utiliza los siguientes pasos para publicar y acceder a los mensajes de registro:

1. Utiliza la StreamingContext clase para publicar información diagnóstica mediante la StreamingDiagnostics.WriteError función. El siguiente código muestra la interfaz que expone Azure Stream Analytics.

   public abstract class StreamingContext
   {
       public abstract StreamingDiagnostics Diagnostics { get; }
   }
   
   public abstract class StreamingDiagnostics
   {
       public abstract void WriteError(string briefMessage, string detailedMessage);
   }
   

2. Pasa StreamingContext como parámetro de entrada al método UDF y úsalo dentro de la UDF para publicar información de registro personalizada. En el siguiente ejemplo, MyUdfMethod se define una entrada de datos , que proporciona la consulta, y una entrada de contexto como , StreamingContextque proporciona el motor de ejecución.

   public static long MyUdfMethod(long data, StreamingContext context)
   {
       // write log
       context.Diagnostics.WriteError("User Log", "This is a log message");
   
       return data;
   }
   

3. Llama a la UDF desde tu consulta. No necesitas pasar el StreamingContext valor en la consulta SQL, porque Azure Stream Analytics proporciona automáticamente un objeto de contexto si hay un parámetro de entrada. El uso de MyUdfMethod no cambia, como se muestra en la siguiente consulta.

   SELECT udf.MyUdfMethod(input.value) as udfValue FROM input
   

4. Accede a los mensajes de registro a través de los registros de diagnóstico.

Contenido relacionado

• Tutorial: Escritura de una función definida por el usuario de C# para un trabajo de Azure Stream Analytics (versión preliminar)
• Tutorial: Funciones definidas por el usuario de JavaScript de Azure Stream Analytics
• Creación de un trabajo de Azure Stream Analytics en Visual Studio Code