Sviluppare funzioni definite dall'utente .NET Standard per i processi di Analisi di flusso di Azure (Ritirato)

Analisi di flusso di Azure offre un linguaggio di query simile a SQL per l'esecuzione di trasformazioni e calcoli su flussi di dati degli eventi. Il linguaggio include molte funzioni integrate, ma alcuni scenari complessi richiedono maggiore flessibilità. Utilizzando le funzioni definite dall'utente (UDF) .NET Standard, puoi invocare le tue funzioni scritte in qualsiasi linguaggio .NET Standard (ad esempio, C# o F#) per estendere il linguaggio di query Stream Analytics. Utilizzare UDF per eseguire calcoli matematici complessi, importare modelli ML personalizzati usando ML.NET e usare logica di imputazione personalizzata per i dati mancanti.

Poiché questa funzione è stata ritirata, usa questo articolo per capire come funzionavano gli UDF Standard .NET e per pianificare la migrazione verso funzioni definite dall'utente in JavaScript.

Informazioni sulle funzioni definite dall'utente dello standard .NET

Gli UDF standard .NET estendono il linguaggio di query di Stream Analytics con logica personalizzata. Prima di costruire un UDF, esamina le regioni in cui la caratteristica viene eseguita, il percorso del pacchetto che utilizza, le mappe di tipo supportate e le limitazioni delle caratteristiche.

Analisi di flusso di Azure abilita la funzione .NET definita dall'utente per i job cloud che vengono eseguiti su cluster Stream Analytics. I lavori che girano sullo SKU multitenant Standard possono utilizzare questa funzione nelle seguenti regioni pubbliche:

• Stati Uniti centro-occidentali
• North Europe
• Stati Uniti orientali
• Stati Uniti occidentali
• Stati Uniti orientali 2
• West Europe

Per utilizzare questa funzione in un'altra regione, richiedi l'accesso.

Il formato di qualsiasi pacchetto UDF ha il percorso /UserCustomCode/CLR/*. Analisi di flusso di Azure copia librerie di link dinamici (DLL) e risorse sotto la /UserCustomCode/CLR/* cartella, aiutando a isolare le DLL degli utenti da quelle di sistema e Analisi di flusso di Azure. Tutte le funzioni utilizzano questo percorso di pacchetto, indipendentemente da come le utilizzi.

Per usare i valori di Analisi di flusso di Azure in C#, è necessario effettuare il marshalling da un ambiente all'altro. Il marshalling avviene per tutti i parametri di input di una funzione definita dall'utente (UDF). Ogni tipo Analisi di flusso di Azure ha un tipo corrispondente in C#, mostrato nella seguente tabella:

Lo stesso vale quando è necessario eseguire il marshalling dei dati da C# ad Analisi di flusso di Azure, operazione che avviene sul valore di output di una UDF. La tabella seguente mostra i tipi supportati:

La caratteristica UDF presenta le seguenti limitazioni:

• Puoi creare UDF standard .NET solo in Visual Studio Code o Visual Studio, e poi pubblicarli su Azure. Puoi visualizzare le versioni in sola lettura degli UDF Standard .NET sotto Funzioni nel portale Azure. Il portale Azure non supporta la creazione di funzioni standard .NET.
• L'editor di query del portale Azure mostra un errore quando usi un UDF .NET Standard nel portale.
• Non puoi chiamare endpoint REST esterni, come fare la ricerca inversa IP o estrarre dati di riferimento da una fonte esterna.
• Poiché il codice personalizzato condivide il contesto con il motore Analisi di flusso di Azure, il codice personalizzato non può fare riferimento a nulla che abbia un nome di namespace o DLL in conflitto con il codice di Analisi di flusso di Azure. Ad esempio, non puoi fare riferimento a Newtonsoft.Json.
• Analisi di flusso di Azure copia i file di supporto nel progetto nel file zip User Custom Code che utilizza quando pubblichi il lavoro sul cloud. Durante la decompressione, tutti i file nelle sottocartelle si spostano alla radice della cartella User Custom Code nel cloud. La decompressione appiattisce il file zip.
• Il codice personalizzato dell'utente non supporta cartelle vuote. Non aggiungere cartelle vuote ai file di supporto nel progetto.

Sviluppare una funzione definita dall'utente in Visual Studio Code

Gli strumenti di Visual Studio Code per Analisi di flusso di Azure semplificano la scrittura di UDF (funzioni definite dall'utente), il test dei processi in locale (anche offline) e la pubblicazione del processo di Stream Analytics in Azure. Puoi implementare UDF standard .NET in Visual Studio Code da un progetto locale o da DLL locali. È anche possibile fare riferimento a DLL locali che includono le funzioni definite dall'utente.

Usa un progetto locale per funzioni complesse che richiedono la piena potenza di un linguaggio standard .NET oltre al suo linguaggio di espressione, come la logica procedurale o la ricorsione. Un progetto locale aiuta anche quando devi condividere la logica delle funzioni tra diverse query Analisi di flusso di Azure, e puoi debugare e testare localmente le tue funzioni. Nel seguente esempio, CSharpUDFProject è un progetto di libreria di classe C#, mentre ASAUDFDemo è il progetto Analisi di flusso di Azure, che fa riferimento a CSharpUDFProject.

1. Crea una nuova libreria di classi .NET Standard sulla tua macchina locale.

   

2. Scrivi il codice nella tua classe. Definisci le classi come pubbliche e gli oggetti come pubblici statici. La seguente UDF moltiplica un intero da sola per produrre il quadrato dell'intero.

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

3. Aggiungi un nuovo file di configurazione di funzione C# nel tuo progetto Analisi di flusso di Azure e fai riferimento al progetto della libreria di classi C#. Per aggiungere la funzione, seleziona e tieni premuto (o clicca con il tasto destro) la cartella Funzioni , poi scegli Aggiungi Elemento.

   

4. Aggiungere una funzione C# SquareFunction al progetto di Analisi di flusso di Azure.

   

5. Inserisci il nome della funzione C#.

   

6. Nella configurazione della funzione C#, seleziona Scegli il percorso del progetto della libreria per scegliere il tuo progetto C# dalla lista a tendina, e seleziona Compila progetto per costruire il tuo progetto. Scegliere quindi Seleziona classe e Seleziona metodo per selezionare la classe e il nome del metodo correlati dall'elenco a discesa. Per fare riferimento ai metodi, ai tipi e alle funzioni nella query Stream Analytics, definisci le classi come pubbliche e gli oggetti come pubblici statici.

   

7. Per usare invece l'UDF C# da una DLL, seleziona Scegli il percorso dll della libreria per scegliere la DLL, poi scegli Select class e Select metodo.

   

8. Richiama la UDF nella query di Analisi di flusso di Azure.

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

9. Configura il percorso assembly nel JobConfig.json file di configurazione del lavoro, nella sezione CustomCodeStorage . Questo passaggio non è necessario per i test locali.

10. Prima di inviare il lavoro ad Azure, configura il percorso del pacchetto nel JobConfig.json file di configurazione del lavoro, nella sezione CustomCodeStorage. Usa Seleziona dalla tua sottoscrizione in CodeLens per scegliere la tua sottoscrizione e seleziona l'account di archiviazione e il nome del contenitore dall'elenco a discesa. Lasciare Il percorso predefinito. Questo passaggio non è necessario per i test locali.

    

Sviluppare una funzione definita dall'utente in Visual Studio

Puoi implementare UDF in Visual Studio usando file CodeBehind in un progetto ASA, un UDF da un progetto locale o un pacchetto esistente da un account di archiviazione Azure. Nel seguente esempio, UDFTest è un progetto di libreria di classe C#, mentre ASAUDFDemo è il progetto Analisi di flusso di Azure, che fa riferimento a UDFTest.

Per l'opzione CodeBehind, scrivi funzioni definite dall'utente nel file CodeBehind Script.asql . Gli strumenti di Visual Studio compilano automaticamente il file CodeBehind in un file assembly. Gli strumenti impacchettano gli assembly come file zip e li caricano sul tuo account di archiviazione quando invii il tuo lavoro ad Azure. Per imparare a scrivere un UDF C# usando CodeBehind, segui il tutorial su C# UDF per i lavori Edge di Stream Analytics .

1. Crea una nuova libreria di classi .NET Standard nella tua soluzione.

   

2. Scrivi il codice nella tua classe. Definisci le classi come pubbliche e gli oggetti come pubblici statici.

3. Crea il progetto. Gli strumenti impacchettano tutti gli artefatti nella cartella bin in un file zip e caricano il file zip sull'account storage. Per i riferimenti esterni, usa un riferimento assembly invece del pacchetto NuGet.

4. Fare riferimento alla nuova classe nel progetto di Analisi di flusso di Azure.

5. Aggiungere una nuova funzione nel progetto di Analisi di flusso di Azure.

6. Configura il percorso assembly nel JobConfig.json file di configurazione del lavoro. Imposta il percorso dell'assembly su Local Project Reference or CodeBehind.

7. Ricompilare sia il progetto di funzione che il progetto di Analisi di flusso di Azure.

8. Costruisci il tuo progetto C# così da poter aggiungere un riferimento al tuo UDF C# dalla query Analisi di flusso di Azure.

   

9. Aggiungere il riferimento al progetto C# nel progetto ASA. Seleziona e tieni premuto (o clicca destro) il nodo Riferimenti , poi scegli Aggiungi Riferimento.

   

10. Scegliere il nome del progetto C# dall'elenco.

    

11. Conferma che UDFTest appare sotto Riferimenti in Esplora soluzioni.

    

12. Seleziona e tieni premuto (o clicca destro) la cartella Functions , poi scegli Nuovo Elemento.

    

13. Aggiungere una funzione C# SquareFunction.json al progetto di Analisi di flusso di Azure.

    

14. Apri la funzione in Esplora soluzioni per visualizzare la finestra di dialogo di configurazione.

    

15. Nella configurazione della funzione C# scegliere Carica dal riferimento al progetto ASA e i nomi di assembly, classe e metodo correlati dall'elenco a discesa. Per fare riferimento ai metodi, ai tipi e alle funzioni nella query Stream Analytics, definisci le classi come pubbliche e gli oggetti come pubblici statici.

    

Configura i pacchetti UDF Standard .NET esistenti

Puoi creare UDF standard .NET in qualsiasi IDE e invocarli dalla tua query Analisi di flusso di Azure. Dopo aver caricato i pacchetti assembly zip sul tuo account di storage Azure, puoi utilizzare le funzioni nelle query di Analisi di flusso di Azure includendo le informazioni di storage nella configurazione del lavoro di Stream Analytics. Non puoi testare la funzione localmente con questa opzione perché gli strumenti di Visual Studio non scaricano il tuo pacchetto. Il servizio analizza direttamente il percorso del pacchetto. Per utilizzare un pacchetto esistente:

1. Compila il tuo codice e impacchetta tutte le DLL usando il percorso /UserCustomCode/CLR/*.

2. Carica UserCustomCode.zip alla radice del container nel tuo account di archiviazione Azure.

3. Nel file di configurazione del processo JobConfig.json, espandi la sezione Configurazione del codice definito dall'utente.

4. Compila la configurazione con i seguenti valori suggeriti.

   Setting	Valore suggerito
   Risorsa delle impostazioni globali di archiviazione	Scegliere la fonte di dati dall'account corrente
   Sottoscrizione delle impostazioni di archiviazione globale	< sottoscrizione >
   Global Storage Settings Storage Account (Account di archiviazione impostazioni di archiviazione globali)	< il tuo account di archiviazione >
   Risorsa delle impostazioni di archiviazione del codice personalizzato	Scegliere la fonte di dati dall'account corrente
   Custom Code Storage Settings Storage Account (Account di archiviazione impostazioni di archiviazione codice personalizzato)	< il tuo account di archiviazione >
   Contenitore delle impostazioni di archiviazione per il codice personalizzato	< il tuo contenitore di archiviazione >
   Origine di codice assembly personalizzato	Pacchetti di assembly esistenti dal cloud
   Origine di codice assembly personalizzato	UserCustomCode.zip

Registra le informazioni personalizzate con la classe StreamingContext

Utilizzando il meccanismo di loging, puoi catturare informazioni personalizzate durante l'esecuzione di un lavoro. Usa i dati di log per debug o valutare in tempo reale la correttezza del codice personalizzato. Usa i seguenti passaggi per pubblicare e accedere ai messaggi di log:

1. Usa la StreamingContext classe per pubblicare informazioni diagnostiche tramite la StreamingDiagnostics.WriteError funzione. Il codice seguente mostra l'interfaccia che Analisi di flusso di Azure espone.

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

2. Passa StreamingContext come parametro di input al metodo UDF e usalo all'interno dell'UDF per pubblicare informazioni di log personalizzate. Nel seguente esempio, MyUdfMethod definisce un input di dati, che viene fornito dalla query, e un input di contesto come StreamingContext, che viene fornito dal motore di esecuzione.

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

3. Chiama l'UDF dalla tua domanda. Non è necessario passare il StreamingContext valore nella query SQL, perché Analisi di flusso di Azure fornisce automaticamente un oggetto contesto se è presente un parametro di input. L'uso di MyUdfMethod non cambia, come mostrato nella seguente richiesta.

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

4. Accedi ai messaggi di log tramite i log diagnostici.

Contenuti correlati

• Esercitazione: Scrivere una funzione C# definita dall'utente per un processo di Analisi di flusso di Azure (anteprima)
• Esercitazione: Funzioni javaScript di Analisi di flusso di Azure definite dall'utente
• Creare un processo di Analisi di flusso di Azure in Visual Studio Code