Desenvolver funções definidas pelo usuário do .NET Standard para trabalhos do Azure Stream Analytics (Desativado)

O Azure Stream Analytics oferece uma linguagem de consulta semelhante a SQL para executar transformações e cálculos em fluxos de dados de eventos. A linguagem inclui muitas funções integradas, mas alguns cenários complexos exigem mais flexibilidade. Ao usar funções definidas pelo usuário (UDF) do .NET Standard, você pode invocar 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 faltantes.

Como esse recurso foi aposentado, use este artigo para entender como funcionavam os UDFs padrão .NET e para planejar sua migração para funções definidas pelo usuário em JavaScript.

Sobre as funções definidas pelo usuário do .NET Standard

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

O Azure Stream Analytics habilita o recurso de função definida pelo usuário .NET para trabalhos em nuvem que rodam em clusters de Stream Analytics. Jobs que rodam no SKU multitenant Standard podem usar esse recurso nas seguintes regiões públicas:

• Centro-oeste dos EUA
• Europa Setentrional
• Leste dos EUA
• Oeste dos EUA
• Leste dos EUA 2
• Oeste da Europa

Para usar esse recurso em outra região, solicite acesso.

O formato de qualquer pacote UDF tem o caminho /UserCustomCode/CLR/*. O Azure Stream Analytics copia bibliotecas de vínculo dinâmico (DLLs) e recursos na pasta /UserCustomCode/CLR/*, o que ajuda a isolar as DLLs do usuário das DLLs do sistema e do Azure Stream Analytics. Todas as funções usam esse caminho de pacote, independentemente de como você as emprega.

Para que os valores do Azure Stream Analytics sejam usados em C#, eles precisam ser convertidos de um ambiente para outro. Marshaling ocorre para todos os parâmetros de entrada de um UDF. Todo tipo Azure Stream Analytics tem um tipo correspondente em C#, mostrado na tabela a seguir:

O mesmo é verdadeiro quando é necessário realizar marshaling dos dados de C# para o Azure Stream Analytics, o que acontece no valor de saída de um UDF. A tabela a seguir mostra os tipos suportados:

O recurso UDF possui as seguintes limitações:

• Você pode criar UDFs padrão .NET apenas no Visual Studio Code ou Visual Studio, e depois publicá-los no Azure. Você pode visualizar versões somente para leitura dos UDFs do .NET Standard em Funções no portal do 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 você usa um UDF .NET Standard no portal.
• Você não pode chamar para endpoints REST externos, como fazer busca reversa de IP ou puxar dados de referência de uma fonte externa.
• Como o código personalizado compartilha contexto com o motor Azure Stream Analytics, o código personalizado não pode referenciar nada que tenha um namespace ou nome DLL conflitante com o código do Azure Stream Analytics. Por exemplo, você não pode referenciar Newtonsoft.Json.
• O Azure Stream Analytics copia os arquivos de suporte do projeto para o arquivo zip User Custom Code, que ele usa quando você publica o trabalho na nuvem. Durante a descompressão, todos os arquivos nas subpastas se movem para a raiz da pasta User Custom Code na nuvem. A descompressão achata o arquivo zip.
• O Código Personalizado do Usuário não dá suporte a pastas vazias. Não adicione pastas vazias aos arquivos de suporte no projeto.

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

As ferramentas do Visual Studio Code para o Azure Stream Analytics facilitam a gravação de UDFs, testem seus trabalhos localmente (mesmo offline) e publiquem seu trabalho do Stream Analytics no Azure. Você pode implementar UDFs padrão .NET no Visual Studio Code a partir de um projeto local ou de DLLs locais. Você também pode referenciar DLLs locais que incluem as funções definidas pelo usuário.

Use um projeto local para funções complexas que exigem todo o poder de uma linguagem padrão .NET além de sua linguagem de expressão, como lógica procedural ou recursão. Um projeto local também ajuda quando você precisa compartilhar a lógica de funções entre várias consultas do Azure Stream Analytics, e você pode depurar e testar suas funções localmente. No exemplo a seguir, CSharpUDFProject é um projeto de biblioteca de classes 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. Escreva o código em sua classe. Defina as classes como públicas e os objetos como públicos estáticos. A UDF a seguir multiplica um inteiro por ele mesmo para obter o quadrado do inteiro.

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

3. Adicione um novo arquivo 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 segure (ou clique com o botão direito) na pasta Funções , e então escolha Adicionar item.

   

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

   

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

   

6. Na configuração da função C#, selecione Escolher caminho de projeto de biblioteca para escolher seu projeto C# na lista suspensa, e selecione Construir projeto para construir seu projeto. Em seguida, escolha Selecionar classe e Selecionar método 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 a UDF em C# 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 a UDF em sua consulta do Azure Stream Analytics.

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

9. Configure o caminho de montagem no JobConfig.json arquivo de configuração do trabalho, na seção CustomCodeStorage . Essa etapa não é necessária para testes locais.

10. Antes de enviar o trabalho para o Azure, configure o caminho do pacote no JobConfig.json arquivo de configuração do trabalho, na seção CustomCodeStorage. Use Selecionar na sua assinatura no CodeLens para escolher sua assinatura e selecione a conta de armazenamento e o nome do contêiner na lista suspensa. Deixe Path como padrão. Essa etapa não é necessária para testes locais.

    

Desenvolver um UDF no Visual Studio

Você pode implementar UDFs no Visual Studio usando arquivos CodeBehind em um projeto ASA, um UDF de um projeto local ou um pacote existente de uma conta de armazenamento Azure. No exemplo a seguir, UDFTest é um projeto de biblioteca de classe C#, e ASAUDFDemo é o projeto Azure Stream Analytics, que faz referência ao UDFTest.

Para a opção CodeBehind, escreva funções definidas pelo usuário no arquivo CodeBehind Script.asql . As ferramentas do Visual Studio compilam automaticamente o arquivo CodeBehind em um arquivo assembly. As ferramentas embalam os assemblies como um arquivo zip e os enviam para sua conta de armazenamento quando você envia seu trabalho para o Azure. Para aprender a escrever uma UDF em C# usando o CodeBehind, siga o tutorial UDF em C# para trabalhos do Stream Analytics Edge.

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

   

2. Escreva o código em sua classe. Defina as classes como públicas e os objetos como públicos estáticos.

3. Compile o projeto. As ferramentas agrupam todos os artefatos da pasta bin em um arquivo zip e enviam o arquivo zip para a conta de armazenamento. Para referências externas, use uma referência de montagem em vez do pacote NuGet.

4. Faça referência à nova classe em seu projeto do Azure Stream Analytics.

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

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

7. Recompile o projeto de funções e o projeto do Azure Stream Analytics.

8. Construa seu projeto em C# para poder adicionar uma referência ao seu UDF de C# a partir da consulta do Azure Stream Analytics.

   

9. Adicione a referência ao projeto C# no projeto ASA. Pressione e mantenha pressionado (ou clique com o botão direito do mouse) o nó Referências e escolha Adicionar Referência.

   

10. Escolha o nome do projeto em C# na lista.

    

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

    

12. Selecione e segure (ou clique com o botão direito) na pasta Funções , e então escolha Novo item.

    

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

    

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

    

15. Na configuração de função C#, escolha Carregar da Referência do Projeto ASA e os nomes de métodos, classe e assembly relacionados 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.

    

Configure pacotes UDF .NET Standard existentes

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

1. Compile seu código e empacote todas as DLLs usando o caminho /UserCustomCode/CLR/*.

2. Faça o upload UserCustomCode.zip para a raiz do contêiner na sua conta de armazenamento do Azure.

3. No arquivo de configuração do trabalho, expanda a seção Configuração de código definida pelo usuário.

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

   Setting	Valor sugerido
   Recurso de Configurações de Armazenamento Global	Selecione a fonte de dados da conta atual
   Assinatura Global de Configurações de Armazenamento	< sua assinatura >
   Configurações Globais de Armazenamento Conta de Armazenamento	< sua conta de armazenamento >
   Recurso de armazenamento de configurações de código personalizadas	Selecione a fonte de dados da conta atual
   Conta de Armazenamento de Configurações de Armazenamento de Código Personalizado	< sua conta de armazenamento >
   Contêiner de configurações de armazenamento de código personalizado	< seu contêiner de armazenamento >
   Fonte do código personalizado de montagem	Pacotes de montagem existentes na cloud
   Fonte do código personalizado de montagem	UserCustomCode.zip

Registre informações personalizadas com a classe StreamingContext

Usando o mecanismo de loging, você pode capturar informações personalizadas 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 acessar mensagens de log:

1. Use a StreamingContext classe para publicar informações diagnósticas usando a StreamingDiagnostics.WriteError função. O código a seguir 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 para o método UDF e use-o dentro do UDF para publicar informações de log personalizadas. No exemplo a seguir, MyUdfMethod define uma entrada de dados , que a consulta fornece, e uma entrada de contexto como , StreamingContextque o motor de runtime fornece.

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

3. Ligue para a UDF a partir da sua consulta. Você não precisa 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 a seguir.

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

4. Acesse as mensagens do log através dos logs de diagnóstico.

Conteúdo relacionado

• Tutorial: Escrever uma função definida pelo usuário em C# para um trabalho do Azure Stream Analytics (versão prévia)
• Tutorial: Funções definidas pelo usuário do JavaScript do Azure Stream Analytics
• Criar um trabalho do Azure Stream Analytics no Visual Studio Code