チュートリアル:Azure Stream Analytics ジョブの C# ユーザー定義関数を記述する (プレビュー)

[アーティクル]
03/06/2024

重要

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

Visual Studio で作成した C# ユーザー定義関数 (UDF) を使用すると、独自の関数で Azure Stream Analytics のクエリ言語を拡張できます。既存のコード (DLL を含む) を再利用し、算術演算ロジックや複雑なロジックを C# で使用することができます。 UDF は次の 3 つの方法で実装できます。

Stream Analytics プロジェクト内の CodeBehind ファイル
ローカル C# プロジェクトの UDF
ストレージアカウントの既存パッケージの UDF

このチュートリアルでは、分離コードの方法を使用して、基本的な C# 関数を実装します。 Stream Analytics ジョブの UDF 機能は現在プレビュー段階にあります。運用環境のワークロードでは使用しないでください。

このチュートリアルでは、以下の内容を学習します。

分離コードを使用して C# のユーザー定義関数を作成する。
Stream Analytics のジョブをローカルでテストする。
ジョブを Azure に発行する。

前提条件

始める前に、以下の前提条件が完了していることを確認してください。

Azure サブスクリプションをお持ちでない場合は、無料アカウントを作成してください。
Visual Studio の Stream Analytics ツールと、Azure 開発ワークロードまたはデータの保存と処理ワークロードをインストールします。
IoT Edge ジョブを作成している場合は、既存の Stream Analytics Edge 開発ガイドを参照してください。

Azure ストレージアカウントでコンテナーを作成する

作成するコンテナーは、コンパイルされた C# パッケージを格納するために使用されます。 Edge ジョブを作成する場合、このストレージアカウントは IoT Edge デバイスへのパッケージのデプロイにも使用されます。 Stream Analytics ジョブごとに専用のコンテナーを使用します。複数の Stream Analytics Edge ジョブに同じコンテナーを再利用することはできません。既存のコンテナーを含むストレージアカウントが既にある場合は、それを使用できます。ない場合は、新しいコンテナーを作成する必要があります。

Visual Studio で Stream Analytics プロジェクトを作成する

Visual Studio を起動します。
[ファイル] > [新規] > [プロジェクト] を選択します。
左側のテンプレートの一覧で [Stream Analytics] を選択し、 [Azure Stream Analytics Edge アプリケーション] または [Azure Stream Analytics アプリケーション] を選択します。
プロジェクトの名前、場所、およびソリューション名を入力し、 [OK] を選択します。

アセンブリパッケージのパスを構成する

Visual Studio を開き、ソリューションエクスプローラーに移動します。
ジョブ構成ファイル JobConfig.json をダブルクリックします。

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

設定	推奨値
グローバルストレージ設定のリソース	現在のアカウントからデータソースを選択します
グローバルストレージ設定のサブスクリプション	< お客様のサブスクリプション >
グローバルストレージ設定のストレージアカウント	< お客様のストレージアカウント >
カスタムコードストレージ設定のリソース	現在のアカウントからデータソースを選択します
カスタムコードストレージ設定のストレージアカウント	< お客様のストレージアカウント >
カスタムコードストレージ設定のコンテナー	< お客様のストレージコンテナー >

分離コードを使用して C# の UDF を作成する

分離コードファイルは、1 つの ASA クエリスクリプトに関連付けられている C# ファイルです。 Visual Studio ツールによって自動的に CodeBehind ファイルが圧縮され、送信時に Azure ストレージアカウントにアップロードされます。すべてのクラスを public として定義し、すべてのオブジェクトを static public として定義する必要があります。

ソリューションエクスプローラーで Script.asql を展開し、Script.asaql.cs 分離コードファイルを探します。

コードを次のサンプルに置き換えます。

    using System; 
    using System.Collections.Generic; 
    using System.IO; 
    using System.Linq; 
    using System.Text; 

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

UDF を実装する

ソリューションエクスプローラーで、Script.asaql ファイルを開きます。

既存のクエリを次のクエリに置き換えます。

    SELECT machine.temperature, udf.ASAEdgeUDFDemo_Class1_SquareFunction(try_cast(machine.temperature as bigint))
    INTO Output
    FROM Input

ローカルテスト

温度シミュレーターサンプルデータファイルをダウンロードします。
ソリューションエクスプローラーで、 [入力] を展開し、Input.json を右クリックして、 [ローカル入力の追加] を選択します。
ダウンロードしたサンプルデータのローカル入力ファイルパスを指定し、 [保存] を選択します。
スクリプトエディターで [ローカルで実行] をクリックします。ローカル実行で出力結果が正常に保存された後、任意のキーを押して、表形式で結果を表示します。
[結果フォルダーを開く] を選択して、JSON および CSV 形式で生ファイルを表示することもできます。

UDF をデバッグする

標準の C# コードをデバッグするのと同じ方法で、C# UDF をローカルにデバッグできます。

C# 関数にブレークポイントを追加します。
F5 キーを押してデバッグを開始します。プログラムは想定どおりにブレークポイントで停止します。

ジョブを Azure に発行する

ローカルでクエリをテストした後、スクリプトエディターで [Azure に送信] を選択して、ジョブを Azure に発行します。

Submit your Stream Analytics Edge job to Azure from Visual Studio

IoT Edge デバイスにデプロイする

Stream Analytics Edge ジョブを作成することを選択した場合に、ジョブを IoT Edge モジュールとしてデプロイできるようになりました。 IoT Edge クイックスタートに従って、IoT ハブを作成し、IoT Edge デバイスを登録し、デバイスに IoT Edge ランタイムをインストールして開始します。次に「ジョブのデプロイ」チュートリアルに従って、Stream Analytics ジョブを IoT Edge モジュールとしてデプロイします。

次のステップ

このチュートリアルでは、分離コードを使用して簡単な C# ユーザー定義関数を作成し、ジョブを Azure に発行し、Azure または IoT Edge デバイスにジョブをデプロイしました。

Stream Analytics ジョブで C# のユーザー定義関数を使用する別の方法の詳細については、次の記事をご覧ください。

Azure Stream Analytics 用の C# 関数を作成する