Разработка стандартных пользовательских функций .NET для заданий Azure Stream Analytics (Отменено)

Azure Stream Analytics предлагает язык запросов, похожий на SQL, для выполнения преобразований и вычислений через потоки данных событий. Язык включает множество встроенных функций, но некоторые сложные сценарии требуют большей гибкости. Используя пользовательские функции (UDF) стандарта .NET, вы можете вызвать свои собственные функции, написанные на любом языке .NET Standard (например, C# или F#), чтобы расширить язык запросов Stream Analytics. Используйте UDF для выполнения сложных математических вычислений, импортируйте пользовательские модели машинного обучения с помощью ML.NET и используйте пользовательскую логику вычисления для отсутствующих данных.

Поскольку эта функция выведена из эксплуатации, используйте эту статью, чтобы понять, как работают стандартные UDF .NET, и спланировать переход к пользовательским функциям JavaScript.

О пользовательских функциях .NET Standard

.NET Standard UDF расширяют язык запросов Stream Analytics пользовательской логикой. Перед созданием UDF изучите регионы, где работает функция, путь пакета, который она использует, поддерживаемые типовые отображения и ограничения по функциям.

Azure Stream Analytics включает пользовательскую функцию .NET для облачных заданий, выполняемых на кластерах Stream Analytics. Задания, работающие на стандартном мультитенантном SKU, могут использовать эту функцию в следующих публичных регионах:

• Центрально-западная часть США
• North Europe
• Восток США
• Западная часть США
• Восток США 2
• West Europe

Чтобы использовать эту функцию в другом регионе, запросите доступ.

Формат любого пакета UDF имеет путь /UserCustomCode/CLR/*. Azure Stream Analytics копирует динамические библиотеки ссылок (DLL) и ресурсы под папкой/UserCustomCode/CLR/*, что помогает изолировать пользовательские DLL от системных и Azure Stream Analytics DLL. Все функции используют этот путь пакета, независимо от того, как вы их используете.

Чтобы значения Azure Stream Analytics использовались в C#, их необходимо маршалировать из одной среды в другую. Маршалинг выполняется для всех входных параметров UDF. Каждый тип Azure Stream Analytics имеет соответствующий тип на C#, указанный в следующей таблице:

То же самое верно, если данные необходимо обрабатывать из C# в Azure Stream Analytics, что происходит на уровне выходного значения UDF. В следующей таблице показаны поддерживаемые типы:

Функция UDF имеет следующие ограничения:

• Вы можете создавать .NET Standard UDF только в Visual Studio Code или Visual Studio, а затем публиковать их в Azure. Вы можете просматривать версии .NET Standard UDF только для чтения в разделе Функции в портале Azure. Портал Azure не поддерживает авторизацию функций .NET Standard.
• Редактор запросов портала Azure показывает ошибку при использовании .NET Standard UDF в портале.
• Нельзя обращаться к внешним конечным точкам REST API, например выполнять обратный поиск по IP-адресу или получать справочные данные из внешнего источника.
• Поскольку пользовательский код использует общий контекст с ядром Azure Stream Analytics, он не может ссылаться на что-либо, имеющее пространство имён или имя DLL, конфликтующее с кодом Azure Stream Analytics. Например, нельзя ссылаться на Newtonsoft.Json.
• Azure Stream Analytics копирует вспомогательные файлы проекта в ZIP-архив User Custom Code, который Azure Stream Analytics использует при публикации задания в облако. Во время распаковки все файлы в подпапках перемещаются в корень папки User Custom Code в облаке. Декомпрессия выравнивает zip-файл.
• Пользовательский код не поддерживает пустые папки. Не добавляйте пустые папки в вспомогательные файлы в проекте.

Разработка UDF в Visual Studio Code

Средства Visual Studio Code для Azure Stream Analytics упрощают создание пользовательских определяемых функций, тестирование заданий локально (даже в автономном режиме) и публикацию задания Stream Analytics в Azure. Вы можете реализовать стандартные UDF .NET в Visual Studio Code как из локального проекта, так и из локальных DLL. Вы также можете ссылаться на локальные библиотеки DLL, включающие определяемые пользователем функции.

Используйте локальный проект для сложных функций, требующих полной мощности стандартного языка .NET, выходящих за рамки языка выражения, таких как процедурная логика или рекурсия. Локальный проект также помогает, когда нужно делиться логикой функций между несколькими запросами Azure Stream Analytics, и вы можете локально отлаживать и тестировать свои функции. В следующем примере CSharpUDFProject — это проект библиотеки класса C#, а ASAUDFDemo — проект Azure Stream Analytics, который ссылается на CSharpUDFProject.

1. Создайте новую библиотеку классов .NET Standard на вашем локальном компьютере.

   

2. Напишите код в классе. Определите классы как публичные , а объекты как статические публичные. Следующий UDF умножает целое число на себя, чтобы получить квадрат целого числа.

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

3. Добавьте новый конфигурационный файл функции C# в ваш проект Azure Stream Analytics и ссылайтесь на проект библиотеки классов C#. Чтобы добавить функцию, выберите и удерживайте (или кликните правой кнопкой) папку Functions , а затем выберите Add Item.

   

4. Добавьте функцию C# SquareFunction в проект Azure Stream Analytics.

   

5. Введите имя функции C#.

   

6. В конфигурации функции C# выберите «Выбрать путь к проекту библиотеки », чтобы выбрать свой проект на C# из выпадающего списка, и выберите «Построить проект » для построения проекта. Затем выберите класс Select и Select method , чтобы выбрать связанный класс и имя метода из раскрывающегося списка. Чтобы ссылаться на методы, типы и функции в запросе Stream Analytics, определите классы как публичные , а объекты — как статические публичные.

   

7. Чтобы использовать C# UDF из DLL вместо этого, выберите Выбрать путь к библиотеке DLL, чтобы указать DLL, затем выберите Выбрать класс и Выбрать метод.

   

8. Вызов UDF в запросе Azure Stream Analytics.

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

9. Настройте путь ассемблера в JobConfig.json файле конфигурации заданий, в разделе CustomCodeStorage . Этот шаг не нужен для локального тестирования.

10. Перед отправкой задания в Azure настройте путь пакета в JobConfig.json конфигурационном файле задания, в разделе CustomCodeStorage. Используйте опцию Select из вашей подписки в CodeLens, чтобы выбрать подписку, а также выберите аккаунт хранения и название контейнера из выпадающего списка. Оставьте путь по умолчанию. Этот шаг не нужен для локального тестирования.

    

Разработка UDF в Visual Studio

Вы можете реализовать UDF в Visual Studio, используя файлы CodeBehind в ASA-проекте, UDF из локального проекта или существующий пакет из аккаунта хранения Azure. В следующем примере UDFTest — это проект библиотеки класса C#, а ASAUDFDemo — проект Azure Stream Analytics, который ссылается на UDFTest.

Для опции CodeBehind записывайте пользовательские функции в файле Script.asql CodeBehind. Инструменты Visual Studio автоматически компилируют файл CodeBehind в ассемблер. Инструменты упаковывают сборки в zip-файл и загружают их в ваш аккаунт хранения при отправке работы в Azure. Чтобы узнать, как написать C# UDF с помощью CodeBehind, следуйте руководству C# UDF для заданий Stream Analytics Edge.

1. Создайте новую библиотеку классов .NET Standard в вашем решении.

   

2. Напишите код в классе. Определите классы как публичные , а объекты как статические публичные.

3. Создайте свой проект. Инструменты упаковывают все артефакты из папки bin в zip-файл и загружают zip-файл в аккаунт хранения. Для внешних ссылок используйте ссылку на ассемблер вместо пакета NuGet.

4. Добавьте ссылку на новый класс в проекте Azure Stream Analytics.

5. Добавьте новую функцию в проект Azure Stream Analytics.

6. Настройте путь ассемблера в JobConfig.json файле конфигурации заданий. Задайте путь ассемблера на Local Project Reference или CodeBehind.

7. Перестройте как проект функции, так и проект Azure Stream Analytics.

8. Постройте свой проект на C# так, чтобы добавить ссылку на ваш C# UDF из запроса Azure Stream Analytics.

   

9. Добавьте ссылку на проект C# в проекте ASA. Выберите и удержите (или кликните правой кнопкой) узел «Ссылки», затем выберите «Добавить ссылку».

   

10. Выберите имя проекта C# в списке.

    

11. Убедитесь, что UDFTest отображается в разделе «Ссылки» в Обозреватель решений.

    

12. Выберите и удерживайте (или кликайте правой кнопкой) папку Functions , а затем выберите New Item.

    

13. Добавьте функцию C# SquareFunction.json в проект Azure Stream Analytics.

    

14. Откройте функцию в Обозреватель решений, чтобы отобразить диалог конфигурации.

    

15. В конфигурации функции C# выберите Load from ASA Project Reference и соответствующую сборку, класс и имена методов из раскрывающегося списка. Чтобы ссылаться на методы, типы и функции в запросе Stream Analytics, определите классы как публичные , а объекты — как статические публичные.

    

Настройка существующих стандартных пакетов UDF .NET

Вы можете создавать .NET Standard UDF в любом IDE и вызывать их из вашего запроса Azure Stream Analytics. После отправки ZIP-пакетов сборок в вашу учётную запись хранения Azure вы сможете использовать функции в запросах Azure Stream Analytics, указав сведения о хранилище в конфигурации задания Stream Analytics. Вы не можете локально протестировать функцию с этой опцией, потому что инструменты Visual Studio не скачивают ваш пакет. Сервис парсирует путь пакета напрямую. Чтобы использовать существующий пакет:

1. Скомпилируйте свой код и упаковайте все DLL, используя путь /UserCustomCode/CLR/*.

2. Загрузите UserCustomCode.zip данные в корень контейнера в вашей учетной записи хранения Azure.

3. В файле конфигурации задания JobConfig.json разверните раздел Конфигурация пользовательского кода.

4. Заполните конфигурацию следующими рекомендуемыми значениями.

   Setting	Рекомендуемое значение
   Глобальный ресурс параметров хранилища	Выбор источника данных из текущей учетной записи
   Подписка на глобальные настройки хранилища	< подписка >
   Глобальные параметры хранения учетной записи хранения	< учетная запись хранения >
   Ресурс параметров хранилища пользовательского кода	Выбор источника данных из текущей учетной записи
   Учетная запись хранения пользовательских параметров хранилища кода	< учетная запись хранения >
   Контейнер параметров хранилища пользовательского кода	< ваш контейнер для хранения >
   Источник сборки пользовательского кода	Существующие пакеты сборок из облака
   Источник сборки пользовательского кода	UserCustomCode.zip

Регистрируйте настраиваемую информацию с помощью класса StreamingContext

Используя механизм логирования, вы можете собирать пользовательскую информацию во время выполнения задачи. Используйте лог-данные для отладки или оценки корректности пользовательского кода в реальном времени. Используйте следующие шаги для публикации и доступа к сообщениям журнала:

1. Используйте StreamingContext класс для публикации диагностической информации с помощью функции StreamingDiagnostics.WriteError . Следующий код показывает интерфейс, который предоставляет 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. Передайте StreamingContext в метод UDF в качестве входного параметра и используйте его в UDF для публикации настраиваемых сообщений журнала. В следующем примере MyUdfMethod определяет входные данные data, которые предоставляет запрос, и входные данные context в качестве StreamingContext, которые предоставляет среда выполнения.

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

3. Позвоните в UDF по вашему запросу. Вам не нужно передавать StreamingContext значение в SQL-запросе, потому что Azure Stream Analytics автоматически предоставляет контекстный объект, если входный параметр присутствует. Использование MyUdfMethod не меняется, как показано в следующем запросе.

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

4. Доступ к сообщениям журнала через диагностические логи.

Связанные материалы

• Руководство. Написание определяемой пользователем функции C# для задания Azure Stream Analytics (предварительная версия)
• Руководство. Определяемые пользователем функции JavaScript для Azure Stream Analytics
• Создание задания Azure Stream Analytics в Visual Studio Code