Desenvolver funções definidas pelo utilizador do .NET Standard para tarefas do Azure Stream Analytics (Descontinuado)

O Azure Stream Analytics oferece uma linguagem de consulta semelhante ao SQL para realizar transformações e cálculos sobre fluxos de dados de eventos. A linguagem inclui muitas funções integradas, mas alguns cenários complexos exigem mais flexibilidade. Ao utilizar funções definidas pelo utilizador (UDF) do .NET Standard, pode invocar as suas próprias funções escritas em qualquer linguagem .NET Standard (por exemplo, C# ou F#) para estender a linguagem de consulta Stream Analytics. Use UDFs para realizar cálculos matemáticos complexos, importe modelos personalizados de ML usando ML.NET e use lógica de imputação personalizada para dados em falta.

Como esta funcionalidade foi retirada, utilize este artigo para compreender como funcionavam os UDFs Padrão .NET e para planear a sua migração para funções definidas pelo utilizador em JavaScript.

Acerca das funções definidas pelo utilizador no .NET Standard

Os UDFs padrão .NET estendem a linguagem de consulta Stream Analytics com lógica personalizada. Antes de construir um UDF, reveja as regiões onde a funcionalidade é executada, o caminho do pacote que utiliza, os mapeamentos de tipos suportados e as limitações das funcionalidades.

O Azure Stream Analytics ativa a funcionalidade de função definida pelo utilizador .NET para trabalhos na cloud que correm em clusters de Stream Analytics. Os trabalhos que correm no SKU multitenant Standard podem usar esta funcionalidade nas seguintes regiões públicas:

• E.U.A. Centro-Oeste
• Europa do Norte
• E.U.A. Leste
• E.U.A. Oeste
• E.U.A. Leste 2
• Europa Ocidental

Para usar esta funcionalidade noutra região, solicite acesso.

O formato de qualquer pacote UDF tem o caminho /UserCustomCode/CLR/*. O Azure Stream Analytics copia bibliotecas de ligação dinâmica (DLLs) e recursos para a pasta /UserCustomCode/CLR/*, o que ajuda a isolar as DLLs dos utilizadores das DLLs do sistema e das DLLs do Azure Stream Analytics. Todas as funções usam este caminho de pacote, independentemente de como as utiliza.

Para que os valores do Azure Stream Analytics sejam usados em C#, precisam de ser organizados de um ambiente para o outro. O marshaling ocorre para todos os parâmetros de entrada de uma UDF. Cada tipo Azure Stream Analytics tem um tipo correspondente em C#, mostrado na tabela seguinte:

O mesmo se aplica quando os dados precisam de ser convertidos de C# para Azure Stream Analytics, isto ocorre no valor de saída de uma UDF. A tabela seguinte mostra os tipos suportados:

A funcionalidade UDF tem as seguintes limitações:

• Podes criar UDFs .NET Standard apenas no Visual Studio Code ou Visual Studio, e depois publicá-los no Azure. Pode ver versões apenas de leitura dos UDFs padrão .NET em Funções no portal Azure. O portal do Azure não suporta a autoria de funções padrão .NET.
• O editor de consultas do portal do Azure mostra um erro quando usas um UDF .NET Standard no portal.
• Não podes ligar para endpoints REST externos, como fazer pesquisa IP reversa ou extrair dados de referência de uma fonte externa.
• Como o código personalizado partilha o contexto com o motor Azure Stream Analytics, o código personalizado não pode referenciar nada que tenha um namespace ou nome DLL conflituoso com o código do Azure Stream Analytics. Por exemplo, não podes referenciar o Newtonsoft.Json.
• O Azure Stream Analytics copia os ficheiros de suporte do projeto para o ficheiro zip User Custom Code que utiliza quando publica o trabalho na cloud. Durante a descompressão, todos os ficheiros nas subpastas movem-se para a raiz da pasta User Custom Code na cloud. A descompressão achata o ficheiro zip.
• O User Custom Code não suporta pastas vazias. Não adicione pastas vazias aos ficheiros de suporte no projeto.

Desenvolver um UDF em Visual Studio Code

As ferramentas do Visual Studio Code para o Azure Stream Analytics facilitam a escrita de UDFs, testar os seus trabalhos localmente (mesmo offline) e publicar os seus trabalhos de Stream Analytics no Azure. Pode implementar UDFs padrão .NET no Visual Studio Code a partir de um projeto local ou de DLLs locais. Também pode referenciar DLLs locais que incluem as funções definidas pelo utilizador.

Use um projeto local para funções complexas que requerem todo o poder de uma linguagem .NET Standard para além da sua linguagem de expressão, como lógica procedural ou recursão. Um projeto local também ajuda quando precisas de partilhar a lógica de funções em várias consultas do Azure Stream Analytics, e podes depurar e testar as tuas funções localmente. No exemplo seguinte, CSharpUDFProject é um projeto de biblioteca de classe C#, e ASAUDFDemo é o projeto Azure Stream Analytics, que faz referência ao CSharpUDFProject.

1. Crie uma nova biblioteca de classes .NET Standard na sua máquina local.

   

2. Escreve o código na tua aula. Defina as classes como públicas e os objetos como públicos estáticos. A seguinte UDF multiplica um número inteiro por ele próprio para obter o respetivo quadrado.

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

3. Adicione um novo ficheiro de configuração de função C# no seu projeto Azure Stream Analytics e consulte o projeto da biblioteca de classes C#. Para adicionar a função, selecione e mantenha pressionado (ou clique com o botão direito) na pasta Funções , e depois escolha Adicionar Item.

   

4. Adicione uma função C# chamada SquareFunction ao seu projeto Azure Stream Analytics.

   

5. Entra o nome da função C#.

   

6. Na configuração da função C#, selecione Escolher caminho de projeto de biblioteca para escolher o seu projeto C# na lista suspensa, e selecione Construir projeto para construir o seu projeto. Depois escolhe Select class e Select method para selecionar a classe relacionada e o nome do método na lista suspensa. Para se referir aos métodos, tipos e funções na consulta Stream Analytics, defina as classes como públicas e os objetos como públicos estáticos.

   

7. Para usar o UDF C# a partir de uma DLL, selecione Escolher o caminho da DLL da biblioteca para escolher a DLL e, em seguida, selecione Selecionar classe e Selecionar método.

   

8. Invoque UDF na sua consulta de Azure Stream Analytics.

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

9. Configure o caminho de montagem no JobConfig.json ficheiro de configuração do trabalho, na secção CustomCodeStorage . Este passo não é necessário para testes locais.

10. Antes de submeter o trabalho para o Azure, configure o caminho do pacote no JobConfig.json ficheiro de configuração do trabalho, na secção CustomCodeStorage. Utilize Selecionar a partir da sua subscrição no CodeLens para escolher a sua subscrição e selecione a conta de armazenamento e o nome do contentor na lista pendente. Deixar Path como predefinição. Este passo não é necessário para testes locais.

    

Desenvolver uma Função Definida pelo Usuário (UDF) no Visual Studio

Pode implementar UDFs no Visual Studio usando ficheiros CodeBehind num projeto ASA, um UDF de um projeto local ou um pacote existente a partir de uma conta de armazenamento Azure. No exemplo seguinte, UDFTest é um projeto de biblioteca de classes C#, e ASAUDFDemo é o projeto Azure Stream Analytics, que faz referência ao UDFTest.

Para a opção CodeBehind, escreva funções definidas pelo utilizador no ficheiro CodeBehind Script.asql . As ferramentas do Visual Studio compilam automaticamente o ficheiro CodeBehind num ficheiro assembly. As ferramentas embalam as assembleias como um ficheiro zip e carregam-nas na tua conta de armazenamento quando submetes o teu trabalho ao Azure. Para aprender a escrever um UDF em C# usando o CodeBehind, siga o tutorial do UDF em C# para trabalhos de Edge em Stream Analytics .

1. Crie uma nova biblioteca de classes .NET Standard na sua solução.

   

2. Escreve o código na tua aula. Defina as classes como públicas e os objetos como públicos estáticos.

3. Construa o seu projeto. As ferramentas empacotam todos os artefactos da pasta bin num ficheiro zip e carregam o ficheiro zip para a conta de armazenamento. Para referências externas, use uma referência de montagem em vez do pacote NuGet.

4. Consulte a nova classe no seu projeto Azure Stream Analytics.

5. Adicione uma nova função no seu projeto Azure Stream Analytics.

6. Configure o caminho de montagem no JobConfig.json ficheiro de configuração do trabalho. Defina o caminho de montagem para Local Project Reference ou CodeBehind.

7. Reconstruir tanto o projeto de funções como o projeto Azure Stream Analytics.

8. Constrói o teu projeto C# para poderes adicionar uma referência ao teu UDF C# a partir da consulta Azure Stream Analytics.

   

9. Adicione a referência ao projeto C# no projeto ASA. Selecione e mantenha premido (ou clique com o botão direito) o nó Referências e, em seguida, selecione Adicionar Referência.

   

10. Escolha o nome do projeto C# da lista.

    

11. Confirme que o UDFTest aparece em Referências no Explorador de Soluções.

    

12. Seleciona e mantém pressionado (ou clica com o botão direito) na pasta Funções , e depois escolhe Novo Item.

    

13. Adicione uma função C#SquareFunction.json ao seu projeto Azure Stream Analytics.

    

14. Abra a função no Explorador de Soluções para mostrar o diálogo de configuração.

    

15. Na configuração da função C#, escolha Carregar da Referência de Projeto ASA e os nomes do assembly, da classe e do método relacionados na lista pendente. Para se referir aos métodos, tipos e funções na consulta Stream Analytics, defina as classes como públicas e os objetos como públicos estáticos.

    

Configurar os pacotes UDF padrão .NET existentes

Pode criar UDFs .NET Standard em qualquer IDE e invocá-los a partir da sua consulta Azure Stream Analytics. Depois de carregar os pacotes assembly zip para a sua conta de armazenamento no Azure, pode usar as funções nas consultas do Azure Stream Analytics incluindo a informação de armazenamento na configuração do trabalho do Stream Analytics. Não podes testar a função localmente com esta opção porque as ferramentas do Visual Studio não descarregam o teu pacote. O serviço analisa diretamente o caminho do pacote. Para usar um pacote existente:

1. Compila o teu código e empacota todas as DLLs usando o caminho /UserCustomCode/CLR/*.

2. Carrega UserCustomCode.zip para a raiz do contentor na tua conta de armazenamento Azure.

3. No ficheiro JobConfig.json de configuração do trabalho, expanda a secção Configuração de Código Definido pelo Utilizador.

4. Preencha a configuração com os seguintes valores sugeridos.

   Setting	Valor sugerido
   Recurso de configurações globais de armazenamento	Escolher fonte de dados da conta corrente
   Subscrição de Definições Globais de Armazenamento	< a sua subscrição >
   Conta de Armazenamento das Configurações Globais	< A sua conta de armazenamento >
   Recurso de definições de armazenamento de código personalizado	Escolher fonte de dados da conta corrente
   Conta de Armazenamento para Configurações de Código Personalizado	< A sua conta de armazenamento >
   Contêiner de configurações de armazenamento de código personalizado	< o seu recipiente de armazenamento >
   Fonte de Montagem de Código Personalizado	Os pacotes de assembly existentes na nuvem
   Fonte de Montagem de Código Personalizado	UserCustomCode.zip

Registar informações personalizadas com a classe StreamingContext

Ao usar o mecanismo de registo, pode capturar informação personalizada enquanto um trabalho é executado. Use dados de log para depurar ou avaliar a correção do código personalizado em tempo real. Use os seguintes passos para publicar e aceder a mensagens de registo:

1. Use a StreamingContext classe para publicar informação de diagnóstico utilizando a StreamingDiagnostics.WriteError função. O código seguinte mostra a interface que o Azure Stream Analytics expõe.

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

2. Passe StreamingContext como parâmetro de entrada ao método UDF e utilize-o dentro da UDF para publicar informação de registo personalizada. No exemplo seguinte, MyUdfMethod define-se uma entrada de dados , que a consulta fornece, e uma entrada de contexto como StreamingContext, que o motor de execução fornece.

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

3. Liga para a UDF a partir da tua consulta. Não precisas de passar o StreamingContext valor na consulta SQL, porque o Azure Stream Analytics fornece automaticamente um objeto de contexto se houver um parâmetro de entrada. O uso de MyUdfMethod não muda, como mostrado na consulta seguinte.

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

4. Aceda às mensagens de registo através dos registos de diagnóstico.

Conteúdo relacionado

• Tutorial: Escreva uma função definida pelo utilizador em C# para um trabalho Azure Stream Analytics (Pré-visualização)
• Tutorial: Azure Stream Analytics Funções definidas pelo utilizador em JavaScript
• Criar uma tarefa "Azure Stream Analytics" no Visual Studio Code