Développer des fonctions définies par l’utilisateur .NET Standard pour les travaux Azure Stream Analytics (Retiré)

Azure Stream Analytics offre un langage de requête de type SQL pour effectuer des transformations et des calculs sur des flux de données d’événement. Le langage inclut de nombreuses fonctions intégrées, mais certains scénarios complexes nécessitent plus de flexibilité. En utilisant les fonctions définies par l’utilisateur (UDF) de la norme .NET, vous pouvez invoquer vos propres fonctions écrites dans n’importe quel langage .NET Standard (par exemple, C# ou F#) pour étendre le langage de requête Stream Analytics. Utilisez des UDF pour effectuer des calculs mathématiques complexes, importez des modèles ML personnalisés en utilisant ML.NET, et utilisez une logique d’imputation personnalisée pour les données manquantes.

Puisque cette fonctionnalité est retirée, utilisez cet article pour comprendre comment fonctionnaient les UDF standards .NET et pour planifier votre migration vers des fonctions définies par l’utilisateur en JavaScript.

À propos des fonctions définies par l’utilisateur de la norme .NET

Les UDF standards .NET étendent le langage de requête Stream Analytics avec une logique personnalisée. Avant de créer un UDF, examinez les régions où la fonctionnalité s’exécute, le chemin du paquet qu’elle utilise, les types de correspondance pris en charge et les limitations des fonctionnalités.

Azure Stream Analytics prend en charge la fonctionnalité de fonction .NET définie par l’utilisateur pour les tâches cloud qui s’exécutent sur des clusters Stream Analytics. Les tâches qui fonctionnent sur le SKU multilocataire Standard peuvent utiliser cette fonctionnalité dans les régions publiques suivantes :

• Ouest du centre des États-Unis
• Europe Nord
• USA Est
• West US
• Est des États-Unis 2
• Europe Ouest

Pour utiliser cette fonctionnalité dans une autre région, demandez l’accès.

Le format d’un package UDF a le chemin d’accès /UserCustomCode/CLR/*. Azure Stream Analytics copie les bibliothèques de liens dynamiques (DLL) et les ressources sous le /UserCustomCode/CLR/* dossier, ce qui aide à isoler les DLL utilisateurs des DLL système et Azure Stream Analytics. Toutes les fonctions utilisent ce chemin de paquet, quelle que soit la manière dont vous les employez.

Pour que les valeurs Azure Stream Analytics soient utilisées en C#, elles doivent être marshalées d’un environnement à l’autre. Le marshaling se produit pour tous les paramètres en entrée d’une fonction définie par l’utilisateur. Chaque type Azure Stream Analytics a un type correspondant en C#, illustré dans le tableau suivant :

Il en va de même lorsque les données doivent être marshalées de C# vers Azure Stream Analytics, ce qui se produit sur la valeur de sortie d’une fonction UDF. Le tableau suivant présente les types pris en charge :

La fonctionnalité UDF présente les limitations suivantes :

• Vous pouvez créer des UDF standards .NET uniquement dans Visual Studio Code ou Visual Studio, puis les publier sur Azure. Vous pouvez consulter les versions en lecture seule des UDF standards .NET sous Fonctions du portail Azure. Le portail Azure ne prend pas en charge la création de fonctions standard .NET.
• L’éditeur de requêtes du portail Azure affiche une erreur lorsque vous utilisez un UDF .NET Standard dans le portail.
• Vous ne pouvez pas appeler des points de terminaison REST externes, comme effectuer une recherche IP inversée ou extraire des données de référence d’une source externe.
• Parce que le code personnalisé partage le contexte avec le moteur Azure Stream Analytics, le code personnalisé ne peut pas référencer un espace de noms ou un nom DLL en conflit avec le code Azure Stream Analytics. Par exemple, vous ne pouvez pas référencer Newtonsoft.Json.
• Azure Stream Analytics copie les fichiers de support du projet dans le fichier zip User Custom Code qu’il utilise lorsque vous publiez le travail dans le cloud. Lors de la décompression, tous les fichiers des sous-dossiers se déplacent vers la racine du dossier Code personnalisé utilisateur dans le cloud. La décompression aplatit le fichier zip.
• Le code personnalisé utilisateur ne prend pas en charge les dossiers vides. N'ajoutez pas de dossiers vides aux fichiers de support dans le projet.

Développer une fonction UDF dans Visual Studio Code

Les outils Visual Studio Code pour Azure Stream Analytics vous facilite l’écriture de fonctions définies par l’utilisateur, le test de vos travaux localement (même en mode hors connexion) et la publication de votre travail Stream Analytics dans Azure. Vous pouvez implémenter des UDF standards .NET dans Visual Studio Code depuis un projet local ou depuis des DLL locaux. Vous pouvez également référencer des DLL locales qui incluent les fonctions définies par l’utilisateur.

Utilisez un projet local pour des fonctions complexes qui nécessitent toute la puissance d’un langage standard .NET au-delà de son langage d’expression, comme la logique procédurale ou la récursion. Un projet local aide aussi lorsque vous devez partager la logique des fonctions entre plusieurs requêtes Azure Stream Analytics, et vous pouvez déboguer et tester vos fonctions localement. Dans l’exemple suivant, CSharpUDFProject est un projet de bibliothèque de classes C#, et ASAUDFDemo est le projet Azure Stream Analytics, qui fait référence à CSharpUDFProject.

1. Créez une nouvelle bibliothèque de classes .NET Standard sur votre machine locale.

   

2. Écrivez le code dans votre classe. Définissez les classes comme publiques et les objets comme publics statiques. L’UDF suivant multiplie un entier par lui-même pour produire le carré de l’entier.

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

3. Ajoutez un nouveau fichier de configuration de fonction C# dans votre projet Azure Stream Analytics, et référez le projet de bibliothèque de classes C#. Pour ajouter la fonction, sélectionnez et maintenez (ou faites clic droit) sur le dossier Fonctions , puis choisissez Ajouter un élément.

   

4. Ajoutez une fonction C# SquareFunction à votre projet Azure Stream Analytics.

   

5. Voici le nom de la fonction C#.

   

6. Dans la configuration de la fonction C#, sélectionnez Choisir le chemin du projet de bibliothèque pour choisir votre projet C# dans la liste déroulante, puis sélectionnez Construire le projet pour construire votre projet. Ensuite, choisissez Sélectionner la classe et la méthode Select pour sélectionner la classe et le nom de la méthode connexes dans la liste déroulante. Pour faire référence aux méthodes, types et fonctions dans la requête Stream Analytics, définissez les classes comme publiques et les objets comme publics statiques.

   

7. Pour utiliser la UDF C# à partir d’une DLL à la place, sélectionnez Choisir le chemin DLL de la bibliothèque pour choisir la DLL, puis sélectionnez Select class et Select méthode.

   

8. Appelez la fonction UDF dans votre requête Azure Stream Analytics.

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

9. Configurez le chemin d’assemblage dans le JobConfig.json fichier de configuration du travail, dans la section CustomCodeStorage . Cette étape n’est pas nécessaire pour les tests locaux.

10. Avant de soumettre le travail à Azure, configurez le chemin du package dans le JobConfig.json fichier de configuration du travail, dans la section CustomCodeStorage. Utilisez Select depuis votre abonnement dans CodeLens pour choisir votre abonnement, et choisissez le compte de stockage et le nom du conteneur dans la liste déroulante. Laissez le chemin d’accès par défaut. Cette étape n’est pas nécessaire pour les tests locaux.

    

Développer une fonction UDF dans Visual Studio

Vous pouvez implémenter des UDF dans Visual Studio en utilisant des fichiers CodeBehind dans un projet ASA, un UDF d’un projet local, ou un package existant depuis un compte de stockage Azure. Dans l’exemple suivant, UDFTest est un projet de bibliothèque de classe C#, et ASAUDFDemo est le projet Azure Stream Analytics, qui fait référence à UDFTest.

Pour l’option CodeBehind, écrivez des fonctions définies par l’utilisateur dans le fichier CodeBehind Script.asql . Les outils de Visual Studio compilent automatiquement le fichier CodeBehind en un fichier assembleur. Les outils emballent les assemblages sous forme de fichier zip et les téléchargent sur votre compte de stockage lorsque vous soumettez votre tâche à Azure. Pour apprendre à écrire une UDF C# à l’aide de CodeBehind, suivez le tutoriel UDF C# pour les travaux Edge Stream Analytics.

1. Créez une nouvelle bibliothèque de classes .NET Standard dans votre solution.

   

2. Écrivez le code dans votre classe. Définissez les classes comme publiques et les objets comme publics statiques.

3. Générez votre projet. Les outils emballent tous les artefacts du dossier bin dans un fichier zip et téléchargent le fichier zip sur le compte de stockage. Pour les références externes, utilisez une référence d’assemblage au lieu du package NuGet.

4. Référencez la nouvelle classe dans votre projet Azure Stream Analytics.

5. Ajoutez une nouvelle fonction dans votre projet Azure Stream Analytics.

6. Configurez le chemin d’assemblage dans le JobConfig.json fichier de configuration du travail. Définissez le chemin d’assemblage sur Local Project Reference ou CodeBehind.

7. Régénérez le projet de fonction et le projet Azure Stream Analytics.

8. Construis ton projet C# pour pouvoir ajouter une référence à ton UDF C# depuis la requête Azure Stream Analytics.

   

9. Ajoutez la référence au projet C# dans le projet ASA. Sélectionnez et maintenez (ou faites un clic droit) sur le nœud Références , puis choisissez Ajouter Référence.

   

10. Choisissez le nom du projet C# dans la liste.

    

11. Confirmez que UDFTest apparaît dans les références dans Explorateur de solutions.

    

12. Sélectionnez et maintenez (ou faites clic droit) sur le dossier Fonctions , puis choisissez Nouvel élément.

    

13. Ajoutez une fonction C# SquareFunction.json à votre projet Azure Stream Analytics.

    

14. Ouvrez la fonction dans l’Explorer de solutions pour afficher la boîte de dialogue de configuration.

    

15. Dans la configuration de la fonction C#, choisissez Load from ASA Project Reference et les noms d'assembly, de classe et de méthode associés dans la liste déroulante. Pour faire référence aux méthodes, types et fonctions dans la requête Stream Analytics, définissez les classes comme publiques et les objets comme publics statiques.

    

Configurez les packages UDF standards .NET existants

Vous pouvez créer des UDF .NET Standard dans n’importe quel IDE et les invoquer depuis votre requête Azure Stream Analytics. Après avoir téléchargé les packages assembly zip sur votre compte de stockage Azure, vous pouvez utiliser les fonctions des requêtes Azure Stream Analytics en incluant les informations de stockage dans la configuration du job Stream Analytics. Vous ne pouvez pas tester la fonction localement avec cette option car les outils Visual Studio ne téléchargent pas votre package. Le service analyse directement le chemin du paquet. Pour utiliser un package existant :

1. Compile ton code et empaquete toutes les DLL en utilisant le chemin /UserCustomCode/CLR/*.

2. Chargez UserCustomCode.zip dans le répertoire racine du conteneur de votre compte de stockage Azure.

3. Dans le JobConfig.json fichier de configuration de la tâche, développez la section Configuration du code défini par l’utilisateur.

4. Complétez la configuration avec les valeurs suggérées suivantes.

   Setting	Valeur suggérée
   Ressource des paramètres globaux de stockage	Choisir une source de données à partir du compte actuel
   Abonnement aux paramètres de stockage global	< votre abonnement >
   Paramètres globaux de stockage Compte de stockage	< votre compte de stockage >
   Paramètres de stockage de code personnalisé Ressource	Choisir une source de données à partir du compte actuel
   Compte de stockage des paramètres de stockage de code personnalisé	< votre compte de stockage >
   Conteneur de paramètres de stockage de code personnalisé	< votre conteneur de stockage >
   Source d’assembly de code personnalisé	Packages d’assembly existants à partir du cloud
   Source d’assembly de code personnalisé	UserCustomCode.zip

Enregistrer les informations personnalisées avec la classe StreamingContext

En utilisant le mécanisme de journalisation, vous pouvez capturer des informations personnalisées pendant l’exécution d’un travail. Utilisez les données de journal pour déboguer ou évaluer en temps réel la correction du code personnalisé. Utilisez les étapes suivantes pour publier et accéder aux messages de journal :

1. Utilisez la StreamingContext classe pour publier des informations diagnostiques en utilisant la StreamingDiagnostics.WriteError fonction. Le code suivant montre l’interface qu’Azure Stream Analytics expose.

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

2. Passer StreamingContext comme paramètre d’entrée à la méthode UDF, et l’utiliser dans la UDF pour publier des informations de journal personnalisées. Dans l’exemple suivant, MyUdfMethod définit une entrée de données , que la requête fournit, et une entrée contextuelle comme , StreamingContextque fournit le moteur d’exécution.

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

3. Appelez l’UDF dans votre requête. Vous n'avez pas besoin de transmettre la StreamingContext valeur dans la requête SQL, car Azure Stream Analytics fournit automatiquement un objet de contexte si un paramètre d'entrée est présent. L’utilisation de MyUdfMethod ne change pas, comme montré dans la requête suivante.

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

4. Accédez aux messages du journal à partir des journaux de diagnostic.

Contenu connexe

• Tutoriel : Écrire une fonction définie par l’utilisateur C# pour un travail Azure Stream Analytics (préversion)
• Tutoriel : Fonctions définies par l'utilisateur JavaScript d'Azure Stream Analytics
• Créer un travail Azure Stream Analytics dans Visual Studio Code