Azure Stream Analytics ジョブ用の .NET Standard ユーザー定義関数を開発する (プレビュー)

[アーティクル]
02/26/2024

重要

Azure Stream Analytics 用の .NET Standard ユーザー定義関数は、2024 年 9 月 30 日に廃止されます。この日付を過ぎると、この機能は使用できなくなります。 Azure Stream Analytics 用の JavaScript ユーザー定義関数に移行してください。

Azure Stream Analytics では、イベントデータのストリームを介して変換や計算を実行するための SQL に似たクエリ言語が提供されます。多くの組み込み関数がありますが、柔軟性を高める必要がある複雑なシナリオもあります。 .NET Standard ユーザー定義関数 (UDF) では、任意の .NET 標準言語 (C#、F# など) で記述された独自の関数を呼び出して、Stream Analytics クエリ言語を拡張できます。 UDF を使用すると、複雑な数学計算の実行や、ML.NET を使用したカスタム ML モデルのインポートが可能になります。また、欠損データにカスタム欠損値補完ロジックを使用することもできます。 Stream Analytics ジョブの UDF 機能は現在プレビュー段階にあります。運用環境のワークロードでは使用しないでください。

リージョン

.NET ユーザー定義関数機能は、Stream Analytics クラスターで実行されるクラウドジョブに対して有効です。 Standard マルチテナント SKU で実行されるジョブでは、次のパブリックリージョンでこの機能を活用できます。

米国中西部
北ヨーロッパ
米国東部
米国西部
米国東部 2
西ヨーロッパ

別のリージョンでこの機能を使用することに関心がある場合は、アクセスを要求することができます。

パッケージパス

UDF パッケージの形式では、パス /UserCustomCode/CLR/* を使用します。ダイナミックリンクライブラリ (DLL) とリソースは /UserCustomCode/CLR/* フォルダーの下にコピーされるので、システム DLL と Azure Stream Analytics DLL からユーザー DLL を分離できます。このパッケージパスは、関数を使用するために使用される方法に関係なく、すべての関数に使用されます。

サポートされている型とマッピング

Azure Stream Analytics の値を C# で使用するためには、環境間でマーシャリングする必要があります。マーシャリングは、UDF のすべての入力パラメーターについて実行されます。次の表に示したように、Azure Stream Analytics のすべての型には、対応する型が C# に存在します。

Azure Stream Analytics の型	C# の型
bigint	long
float	double
nvarchar(max)	string
DATETIME	DateTime
Record	ディクショナリ<文字列、オブジェクト>
Array	Object[]

C# から Azure Stream Analytics へのデータのマーシャリング (UDF の出力値に対して実行されます) にも同じことが言えます。サポートされる型を次の表に示します。

C# の型	Azure Stream Analytics の型
long	bigint
double	float
string	nvarchar(max)
DateTime	dateTime
struct	Record
object	Record
Object[]	Array
ディクショナリ<文字列、オブジェクト>	Record

Visual Studio Code で UDF を開発する

Azure Stream Analytics 用 Visual Studio Code ツールを使用すると、UDF の記述、ローカルでのジョブのテスト (オフラインでも可能)、Azure への Stream Analytics ジョブの発行が容易になります。

Visual Studio Code ツールで .NET Standard UDF を実装する方法は 2 つあります。

ローカル DLL の UDF
ローカルプロジェクトの UDF

ローカルプロジェクト

ユーザー定義関数は、後で Azure Stream Analytics クエリで参照されるアセンブリに記述できます。これは、手続き型ロジックや再帰など、式言語の枠を超えて .NET Standard 言語の機能を最大限に活用する必要がある複雑な関数に推奨される方法です。複数の Azure Stream Analytics クエリで関数ロジックを共有する必要がある場合は、ローカルプロジェクトの UDF を使用することもできます。 UDF をローカルプロジェクトに追加すると、ローカルで関数をデバッグしてテストすることができます。

ローカルプロジェクトを参照するには、次の手順に従います。

新しい .NET 標準クラスライブラリをローカルマシンに作成します。
クラスにコードを記述します。クラスは public として定義し、オブジェクトは static public として定義する必要があることに注意してください。
新しい CSharp 関数構成ファイルを Azure Stream Analytics プロジェクトに追加し、CSharp クラスライブラリプロジェクトを参照します。
ジョブ構成ファイル JobConfig.json の JobConfig.json セクションで、アセンブリパスを構成します。この手順は、ローカルテストでは必要ありません。

ローカル DLL

また、ユーザー定義関数を含むローカル DLL を参照することもできます。

例

この例で、CSharpUDFProject は C# クラスライブラリプロジェクトです。ASAUDFDemo は Azure Stream Analytics プロジェクトであり、CSharpUDFProject を参照します。

Azure Stream Analytics project in Visual Studio Code

次の UDF には、整数の 2 乗を生成するために、整数にそれ自体を乗算する関数があります。各クラスは public として定義し、各オブジェクトは static public として定義する必要があります。

using System;

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

次の手順は、Stream Analytics プロジェクトに C# UDF 関数を追加する方法を示しています。

[関数] フォルダーを右クリックし、 [項目の追加] を選択します。
Azure Stream Analytics プロジェクトに、C# 関数 SquareFunction を追加します。
C# 関数の構成で、 [Choose library project path](ライブラリプロジェクトパスの選択) を選択して、ドロップダウンリストから C# プロジェクトを選択します。 [プロジェクトのビルド] を選択して、プロジェクトをビルドします。次に、 [クラスの選択] と [メソッドの選択] を選択し、ドロップダウンリストから関連するクラスおよびメソッドの名前を選択します。 Stream Analytics クエリでメソッド、型、関数を参照するには、クラスを public として定義し、オブジェクトを static public として定義する必要があります。

DLL の C# UDF を使用する場合は、 [Choose library dll path](ライブラリ DLL のパスの選択) を選択し、DLL を選択します。次に、 [クラスの選択] と [メソッドの選択] を選択し、ドロップダウンリストから関連するクラスおよびメソッドの名前を選択します。

Azure Stream Analytics クエリで、UDF を呼び出します。

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

Azure にジョブを送信する前に、ジョブ構成ファイル JobConfig.json の JobConfig.json セクションで、パッケージパスを構成します。 CodeLens の [Select from your subscription](サブスクリプションから選択) を使用してサブスクリプションを選択し、ドロップダウンリストからストレージアカウントとコンテナー名を選択します。 [パス] は既定値のままにします。ローカルテストでは、この手順は必要ありません。

Visual Studio で UDF を開発する

Visual Studio ツールで UDF を実装する方法は、3 つあります。

ASA プロジェクト内の分離コードファイル
ローカルプロジェクトの UDF
Azure ストレージアカウントの既存のパッケージ

分離コード

Script.asql 分離コードにユーザー定義関数を記述できます。 Visual Studio Tools により、分離コードファイルがアセンブリファイルに自動的にコンパイルされます。ジョブを Azure に送信すると、アセンブリが ZIP ファイルとしてパッケージ化され、ストレージアカウントにアップロードされます。分離コードを使用して C# UDF を記述する方法については、Stream Analytics Edge ジョブの C# UDF に関するチュートリアルをご覧ください。

ローカルプロジェクト

Visual Studio でローカルプロジェクトを参照するには:

ソリューションに新しい .NET 標準クラスライブラリを作成します
クラスにコードを記述します。クラスは public として定義し、オブジェクトは static public として定義する必要があることに注意してください。
プロジェクトをビルドします。ツールによって、bin フォルダー内のすべての成果物が ZIP ファイルにパッケージ化され、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# プロジェクトをビルドします。これにより、Azure Stream Analytics クエリから C# UDF への参照を追加できるようになります。
ASA プロジェクトに C# プロジェクトへの参照を追加します。 [参照] ノードを右クリックし、[参照の追加] を選択します。
一覧から C# プロジェクト名を選択します。
ソリューションエクスプローラーの [参照] の下に [UDFTest] が表示されます。
[関数] フォルダーを右クリックし、 [新しいアイテム] を選択します。
Azure Stream Analytics プロジェクトに、C# 関数 SquareFunction.json を追加します。
ソリューションエクスプローラーで関数をダブルクリックして、構成ダイアログを開きます。
C# 関数の構成で、 [Load from ASA Project Reference](ASA プロジェクト参照から読み込む) を選択し、ドロップダウンリストから関連するアセンブリ、クラス、メソッドの名前を選択します。 Stream Analytics クエリでメソッド、型、関数を参照するには、クラスを public として定義し、オブジェクトを static public として定義する必要があります。

既存のパッケージ

任意の IDE で .NET Standard UDF を作成し、Azure Stream Analytics クエリから呼び出すことができます。まず、コードをコンパイルし、すべての DLL をパッケージ化します。パッケージの形式では、パス /UserCustomCode/CLR/* を使用します。その後、Azure ストレージアカウントのコンテナーのルートに UserCustomCode.zip をアップロードします。

アセンブリの zip パッケージが Azure ストレージアカウントにアップロードされたら、Azure Stream Analytics クエリで関数を使用できます。必要なのは、Stream Analytics ジョブ構成にストレージ情報を含めることだけです。 Visual Studio Tools ではパッケージをダウンロードしないため、このオプションを使用して関数をローカルでテストすることはできません。パッケージパスはサービスに直接解析されます。

ジョブ構成ファイル (JobConfig.json) でアセンブリパスを構成するには、次の操作を行います。

[User-Defined Code Configuration](ユーザー定義コードの構成) セクションを展開し、構成に次の推奨値を入力します。

設定	推奨値
グローバルストレージ設定のリソース	現在のアカウントからデータソースを選択します
グローバルストレージ設定のサブスクリプション	< お客様のサブスクリプション >
グローバルストレージ設定のストレージアカウント	< お客様のストレージアカウント >
カスタムコードストレージ設定のリソース	現在のアカウントからデータソースを選択します
カスタムコードストレージ設定のストレージアカウント	< お客様のストレージアカウント >
カスタムコードストレージ設定のコンテナー	< お客様のストレージコンテナー >
カスタムコードアセンブリソース	クラウドの既存のアセンブリパッケージ
カスタムコードアセンブリソース	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 は、UDF メソッドに入力パラメーターとして渡され、UDF 内で使用してカスタムログ情報を発行できます。次の例では、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

ログメッセージにアクセスするには、診断ログを使用します。

制限事項

現在、UDF プレビューには次の制限があります。

.NET Standard UDF は Visual Studio Code または Visual Studio でのみ作成でき、Azure に発行できます。 Azure portal の [関数] には、.NET Standard UDF の読み取り専用バージョンが表示されます。 .NET Standard 関数の作成は、Azure portal ではサポートされていません。
Azure portal で .NET Standard UDF を使用すると、ポータルのクエリエディターにエラーが表示されます。
外部の REST エンドポイントの呼び出し (IP の逆引き参照の実行、外部ソースからの参照データのプルなど)
カスタムコードは Azure Stream Analytics エンジンとコンテキストを共有するため、名前空間/dll_name が Azure Stream Analytics コードと競合するものをカスタムコードで参照することはできません。たとえば、Newtonsoft Json を参照することはできません。
プロジェクトに含まれるサポートファイルは、ジョブをクラウドに発行するときに使用されるユーザーカスタムコード zip ファイルにコピーされます。サブフォルダー内のすべてのファイルは、解凍時に、クラウド内のユーザーカスタムコードフォルダーのルートに直接コピーされます。この zip は、圧縮解除時に "フラット化" されます。
ユーザーカスタムコードでは、空のフォルダーはサポートしていません。プロジェクトのサポートファイルに空のフォルダーは追加しないでください。

次の方法で共有

Azure Stream Analytics ジョブ用の .NET Standard ユーザー定義関数を開発する (プレビュー)

リージョン

パッケージパス

サポートされている型とマッピング

Visual Studio Code で UDF を開発する

ローカルプロジェクト

ローカル DLL

例

Visual Studio で UDF を開発する

分離コード

ローカルプロジェクト

例

既存のパッケージ

ユーザーのログ記録

制限事項

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Stream Analytics ジョブ用の .NET Standard ユーザー定義関数を開発する (プレビュー)

リージョン

パッケージ パス

サポートされている型とマッピング

Visual Studio Code で UDF を開発する

ローカル プロジェクト

ローカル DLL

例

Visual Studio で UDF を開発する

分離コード

ローカル プロジェクト

例

既存のパッケージ

ユーザーのログ記録

制限事項

次のステップ

フィードバック

その他のリソース

パッケージパス

ローカルプロジェクト

ローカルプロジェクト