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

Статья
02/26/2024

Внимание

Определяемые пользователем функции .Net Standard для Azure Stream Analytics будут прекращены 30 сентября 2024 года. По истечении этой даты невозможно использовать эту функцию. Перейдите к определяемым пользователем функциям JavaScript для Azure Stream Analytics.

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

Регионы

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

Центрально-западная часть США
Северная Европа
Восточная часть США
Западная часть США
Восточная часть США 2
Западная Европа

Если вы заинтересованы в использовании этой возможности в другом регионе, можно запросить доступ.

Путь пакета

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

Поддерживаемые типы и сопоставление

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

Тип Azure Stream Analytics	Тип C#
bigint	длинный
с плавающей запятой	двойной точности
nvarchar(max)	строка
datetime	DateTime
Запись	Словарь<строка, объект>
Массив	Object[]

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

Тип C#	Тип Azure Stream Analytics
длинный	bigint
двойной точности	с плавающей запятой
строка	nvarchar(max)
DateTime	dateTime
struct	Запись
объект	Запись
Object[]	Массив
Словарь<строка, объект>	Запись

Разработка определяемой пользователем функции в Visual Studio Code

Инструменты Visual Studio Code для Azure Stream Analytics позволяют легко создавать пользовательские функции, локально тестировать задания (даже в автономном режиме) и публиковать задания Stream Analytics в Azure.

В инструментах Visual Studio Code существует два способа реализации определяемых пользователем функций .NET Standard.

Определяемая пользователем функция из локальных библиотек DLL
пользовательская функция из локального проекта;

Локальный проект

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

Создание ссылки на локальный проект

Создайте новую библиотеку классов .NET Standard на локальном компьютере.
Напишите код в классе. Обратите внимание, что классы должны быть определены как public, а объекты — как static public.
Добавьте новый файл конфигурации функции CSharp в проект Azure Stream Analytics и ссылку на проект библиотеки классов CSharp.
Укажите путь к сборке в файле конфигурации задания, JobConfig.json в разделе CustomCodeStorage. Для локального тестирования этот шаг не требуется.

Локальные библиотеки DLL

Также можно ссылаться на локальные библиотеки DLL, включающие определяемые пользователем функции.

Пример

В этом примере CSharpUDFProject — это проект библиотеки классов C#, а ASAUDFDemo — проект Azure Stream Analytics, который будет ссылаться на CSharpUDFProject.

Azure Stream Analytics project in Visual Studio Code

В следующей определяемой пользователем функции предусмотрена функция, которая умножает целочисленное значение на само это значение, чтобы получить квадрат целого числа. Классы должны быть определены как public, а объекты — как static public.

using System;

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

Ниже описано, как добавить функцию в определяемой пользователем функции C# в проект Stream Analytics.

Щелкните правой кнопкой мыши папку Функции и выберите Добавить элемент.
Добавьте функцию C# SquareFunction в проект Azure Stream Analytics.
В конфигурации функции C# выберите Choose library project path (Выбрать путь к проекту библиотеки), чтобы выбрать проект C# из раскрывающегося списка, и выберите Собрать проект, чтобы скомпилировать проект. Затем выберите Выбрать класс и Выбрать метод, чтобы выбрать из раскрывающегося списка связанные имена класса и метода. Для ссылки на методы, типы и функции в запросе в Stream Analytics классы должны быть определены как public, а объекты — как static public.

Если вы хотите использовать определяемую пользователем функцию C# из библиотеки DLL, выберите выбрать Choose library dll path (Выбрать путь к библиотеке DLL), чтобы выбрать библиотеку DLL. Затем выберите Выбрать класс и Выбрать метод, чтобы выбрать из раскрывающегося списка связанные имена класса и метода.
Вызовите определяемую пользователем функцию в запросе Azure Stream Analytics.
```
 SELECT price, udf.SquareFunction(price)
 INTO Output
 FROM Input 
```
Перед отправкой задания в Azure настройте путь к пакету в файле конфигурации задания JobConfig.json в разделе CustomCodeStorage. Используйте параметр Select from your subscription (Выбрать из подписки) в CodeLens, чтобы выбрать подписку и учетную запись хранения, а также имя контейнера из раскрывающегося списка. Для пути оставьте значение по умолчанию. Этот шаг не требуется для локального тестирования.

Разработка определяемой пользователем функции в Visual Studio

Существует три способа реализации определяемой пользователем функции в средствах Visual Studio.

файлы CodeBehind в проекте ASA;
пользовательская функция из локального проекта;
существующий пакет из учетной записи хранения Azure.

CodeBehind

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

Локальный проект

Для ссылки на локальный проект в Visual Studio выполните следующие действия.

Создайте в решении новую библиотеку классов .NET Standard.
Напишите код в классе. Обратите внимание, что классы должны быть определены как public, а объекты — как static public.
Выполните сборку проекта. Средства упакуют все артефакты в папке bin и передадут ZIP-файл в учетную запись хранения. Для внешних ссылок используйте ссылку на сборку, а не пакет NuGet.
Сошлитесь на новый класс в проекте Azure Stream Analytics.
Добавьте новую функцию в проект Azure Stream Analytics.
Настройте путь к сборке в файле конфигурации задания JobConfig.json. В качестве пути к сборке укажите ссылку на локальный проект или код программной части.
Выполните повторную сборку проекта функций и проекта Azure Stream Analytics.

Пример

В этом примере UDFTest — проект библиотеки классов C#, а ASAUDFDemo — проект Azure Stream Analytics, который будет ссылаться на UDFTest.

Azure Stream Analytics IoT Edge project in Visual Studio

Создайте проект на C#, который позволит добавить ссылку на пользовательскую функцию C# из запроса Azure Stream Analytics.
Добавьте ссылку на проект C# в проекте ASA. Щелкните правой кнопкой мыши узел "Ссылки" и выберите "Добавить ссылку".
Выберите имя проекта C# в списке.
В списке Ссылки в обозревателе решений должен отобразиться проект UDFTest.
Щелкните правой кнопкой мыши папку Функции и выберите Новый элемент.
Добавьте функцию C# SquareFunction.json в проект Azure Stream Analytics.
Дважды щелкните функцию в обозревателе решений, чтобы открыть диалоговое окно настройки.
В окне настройки функции C# выберите Загрузить из ссылки на проект ASA и щелкните имена связанных сборки, класса и метода в раскрывающемся списке. Для ссылки на методы, типы и функции в запросе в Stream Analytics классы должны быть определены как public, а объекты — как static public.

Существующие пакеты

Вы можете создать пользовательские функции .NET Standard в любой IDE на ваш выбор и вызвать их из запроса Azure Stream Analytics. Сначала скомпилируйте код и упакуйте все библиотеки DLL. Формат пакета имеет путь /UserCustomCode/CLR/*. После отправьте UserCustomCode.zip в корень контейнера в учетной записи хранения Azure.

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

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

Разверните раздел Настройка пользовательского кода и укажите следующие предложенные значения в конфигурации:

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

Ведение журнала пользователя

Механизм ведения журнала позволяет собирать определенные сведения во время выполнения задания. Данные журнала можно использовать для отладки или оценки правильности пользовательского кода в реальном времени.

Класс 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);
}

StreamingContext передается в качестве входного параметра в метод определяемой пользователем функции и может использоваться в этой функции для публикации данных настраиваемого журнала. В приведенном ниже примере MyUdfMethod определяет входные данные, предоставляемые запросом, и входной контекст в виде контекста StreamingContext, предоставляемого подсистемой среды выполнения.

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

Передавать значение StreamingContext в SQL-запросе не требуется. При наличии входного параметра Azure Stream Analytics предоставляет объект контекста автоматически. Как показано в следующем запросе, использование MyUdfMethod при этом не изменится.

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

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

Ограничения

Предварительная версия пользовательских функций сейчас имеет следующие ограничения.

Пользовательские функции .NET Standard можно создать только в Visual Studio Code или Visual Studio и опубликовать в Azure. Версии пользовательских функций .NET Standard только для чтения можно просмотреть в разделе Функции на портале Azure. Создание функций .NET Standard не поддерживается на портале Azure.
Редактор запросов на портале Azure отображает ошибку при использовании пользовательской функции .NET Standard на портале.
Вызов внешних конечных точек REST, например выполнение обратного разрешения IP-адресов или извлечение ссылочных данных из внешнего источника.
Так как пользовательский код имеет общий контекст с подсистемой Azure Stream Analytics, он не может содержать ссылки на объекты с конфликтующим значением namespace/dll_name в коде Azure Stream Analytics. Например, ссылки на Newtonsoft Json запрещены.
Вспомогательные файлы, включенные в проект, копируются в ZIP-файл настраиваемого кода пользователя, который используется при публикации задания в облаке. Все файлы во вложенных папках копируются при распаковке непосредственно в корень папки настраиваемого кода пользователя в облаке. При распаковке ZIP-файл преобразуется в плоскую структуру.
Настраиваемый код пользователя не поддерживает пустые папки. Не добавляйте пустые папки во вспомогательные файлы проекта.

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

Регионы

Путь пакета

Поддерживаемые типы и сопоставление

Разработка определяемой пользователем функции в Visual Studio Code

Локальный проект

Локальные библиотеки DLL

Пример

Разработка определяемой пользователем функции в Visual Studio

CodeBehind

Локальный проект

Пример

Существующие пакеты

Ведение журнала пользователя

Ограничения

Следующие шаги

Дополнительные ресурсы