針對 Azure 串流分析作業開發 .NET Standard 使用者定義的函式 (預覽)

  • 發行項

重要

Azure 串流分析的 .NET Standard 使用者定義函式將於 2024 年 9 月 30 日淘汰。 在該日期之後，將無法使用該功能。 請轉換至適用於 Azure 串流分析的 JavaScript 使用者定義函式。

Azure 串流分析提供類似 SQL 的查詢語言，以對事件資料的串流執行轉換與計算。 內建許多函式，但某些複雜的案例需要更大的彈性。 透過 .NET Standard 使用者定義的函式 (UDF)，您可以叫用任何以 .NET Standard 語言 (C#、F# 等) 撰寫的函式，以擴充串流分析查詢語言。 UDF 可讓您執行複雜的數學運算、使用 ML.NET 匯入自訂 ML 模型，及為遺漏的資料使用自訂插補邏輯。 適用於串流分析作業的 UDF 功能目前為預覽狀態，不應該用於生產環境工作負載。

地區

.NET 使用者定義函式功能適用於串流分析叢集上執行的雲端作業。 在標準多租用戶 SKU 上執行的作業可以在下列公用區域中利用此功能：

  • 美國中西部
  • 北歐
  • 美國東部
  • 美國西部
  • 美國東部 2
  • 西歐

如果有興趣於其他任何區域中使用此功能，您可以要求存取。

封裝路徑

任何 UDF 封裝格式的路徑皆為 /UserCustomCode/CLR/*。 動態連結程式庫 (DLL) 與資源會複製到 /UserCustomCode/CLR/* 資料夾下方，這可幫助將使用者 DLL 與系統和 Azure 串流分析 DLL 隔離。 此套件路徑用於所有函式，而不論用來運用它們的方法為何。

支援的型別與對應

Azure 串流分析值必須在兩個環境之間封送處理，才能在 C# 中使用。 UDF 的所有輸入參數都封送處理。 每個 Azure 串流分析型別在 C# 中都有對應的類型，如下表所示：

Azure 串流分析型別 C# 型別
bigint long
FLOAT double
nvarchar(max) string
Datetime Datetime
錄製 Dictionary<string, object>
陣列 Object[]

在 UDF 的輸出值上需要將資料從 C# 封送處理到 Azure 串流分析時，也是如此。 下表顯示支援的型別：

C# 型別 Azure 串流分析型別
long bigint
double float
string nvarchar(max)
Datetime dateTime
struct 錄製
object 錄製
Object[] 陣列
Dictionary<string, object> 錄製

在 Visual Studio Code 中開發 UDF

Azure 串流分析的 Visual Studio Code 工具可讓您輕鬆撰寫 UDF、在本機 (甚至離線) 測試作業，並將串流分析作業發佈至 Azure。

在 Visual Studio Code 工具中實作 .NET 標準 UDF 有兩種方式。

  • 來自本機 DLL 的 UDF
  • 本機檔案的 UDF

本機專案

使用者定義的函式可在 Azure 串流分析查詢稍後參照的組件中撰寫。 對於需要 .NET Standard 語言完整功能 (例如程序邏輯或遞迴) 超出其運算式語言之外的複雜函式，建議使用此選項。 本機專案的 UDF 也可用於您必須在數個 Azure 串流分析查詢之間共用函式邏輯的時候。 將 UDF 新增至本機專案可讓您在本機偵錯和測試函式。

若要參照本機專案：

  1. 在本機電腦上建立新的 .NET 標準類別庫。
  2. 在您的類別中撰寫程式碼。 請記住，類別必須定義成公用，物件必須定義成靜態公用。
  3. 在 Azure 串流分析專案中新增 CSharp 函式組態檔，並參考 CSharp 類別庫專案。
  4. 在作業組態檔 JobConfig.json 的 CustomCodeStorage 區段中設定組件路徑。本機測試不需要此步驟。

本機 DLL

您也可以參考包含使用者定義函式的本機 DLL。

範例

在此範例中，CSharpUDFProject 是 C# 類別庫專案，ASAUDFDemo 是 Azure 串流分析專案 (參考 CSharpUDFProject)。

Azure Stream Analytics project in Visual Studio Code

下列 UDF 有一個函式將整數自乘，以得到該整數的平方。 類別必須定義為 public，物件必須定義為 static public。

using System;

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

下列步驟說明如何將 C# UDF 函式新增至串流分析專案。

  1. 以滑鼠右鍵按一下 Functions 資料夾，然後選擇 [新增項目]。

    Add new function in Azure Stream Analytics project

  2. 將 C# 函式 SquareFunction 新增至 Azure 串流分析專案。

    Select CSharp function from Stream Analytics project in VS Code

    Enter CSharp function name in VS Code

  3. 在 C# 函式設定中，選取 [選擇程式庫專案路徑]，從下拉式清單中選擇您的 C# 專案，然後選取 [組建專案] 以組建專案。 然後選擇 [選取類別] 和 [選取方法]，從下拉式清單中選取相關的類別和方法名稱。 若要在串流分析查詢中參考方法、型別和函式，類別必須定義為 public，物件必須定義為 static public。

    Stream Analytics C sharp function configuration VS Code

    如果要使用來自 DLL 的 C# UDF，請選取 [選擇程式庫 DLL 路徑] 以選擇 DLL。 然後選擇 [選取類別] 和 [選取方法]，從下拉式清單中選取相關的類別和方法名稱。

    Stream Analytics C sharp function configuration

  4. 在 Azure 串流分析查詢中叫用 UDF。

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

  5. 將作業提交至 Azure 之前，請在作業組態檔 JobConfig.json 的 CustomCodeStorage 區段中設定封裝路徑。 在 CodeLens 中使用 [從訂用帳戶選取] 來選擇您的訂用帳戶，然後從下拉式清單中選擇儲存體帳戶和容器名稱。 將 [路徑] 維持預設。 本機測試不需要此步驟。

    Choose library path

在 Visual Studio 中開發 UDF

在 Visual Studio 工具中實作 UDF 有三種方式。

  • ASA 專案中的 CodeBehind 檔案
  • 本機檔案的 UDF
  • Azure 儲存體帳戶的現有封裝

CodeBehind

您可以使用 Script.asql CodeBehind 撰寫使用者定義的函式。 Visual Studio 工具會自動將 CodeBehind 檔案編譯成組件檔。 組件會封裝為 zip 檔案，並在您將工作提交到 Azure 時上傳到您的儲存體帳戶。 您可以遵循 針對 Azure 串流分析 Edge 作業撰寫 C# UDF 教學課程，了解如何使用 CodeBehind 撰寫 C# UDF。

本機專案

若要在 Visual Studio 中參考本機專案：

  1. 在方案中建立新的 .NET 標準類別庫
  2. 在您的類別中撰寫程式碼。 請記住，類別必須定義成公用，物件必須定義成靜態公用。
  3. 建立您的專案。 工具會將 bin 資料夾中的所有成品封裝為 ZIP 檔案，並將 ZIP 檔案上傳至儲存體帳戶。 針對外部參考，請使用組件參考，而不要使用 NuGet 套件。
  4. 在您的 Azure 串流分析專案中參照新類別。
  5. 在您的 Azure 串流分析專案中新增新的函式。
  6. 在工作組態檔案中設定組件路徑，JobConfig.json。 將組件路徑設定為 [本機專案參考或 CodeBehind]。
  7. 重建函式專案與 Azure 串流分析專案。

範例

在此範例中，UDFTest 是 C# 類別庫專案，ASAUDFDemo 是 Azure 串流分析專案 (參考 UDFTest)。

Azure Stream Analytics IoT Edge project in Visual Studio

  1. 建置您的 C# 專案，讓您能夠從 Azure 串流分析查詢新增對您 C# UDF 的參照。

    Build an Azure Stream Analytics IoT Edge project in Visual Studio

  2. 在 ASA 專案中新增 C# 專案的參考。 以滑鼠右鍵按一下 [參照] 節點，然後選擇 [新增參照]。

    Add a reference to a C# project in Visual Studio

  3. 從清單中選擇 C# 專案名稱。

    Choose your C# project name from the reference list

  4. 您應該會在 [方案總管] 中 [參照] 的下方看見 [UDFTest]。

    View the user defined function reference in solution explorer

  5. 以滑鼠右鍵按一下 [函式] 資料夾，然後選擇 [新項目]。

    Add new item to Functions in Azure Stream Analytics Edge solution

  6. 將 C# 函式 SquareFunction.json 新增至 Azure 串流分析專案。

    Select CSharp function from Stream Analytics Edge items in Visual Studio

  7. 按兩下 [方案總管] 中的函式，以開啟設定對話方塊。

    C sharp function configuration in Visual Studio

  8. 在 C# 函式設定中，選擇 [從 ASA 專案參照載入]，然後從下拉式清單中選擇相關的組件、類別與方法名稱。 若要在串流分析查詢中參考方法、型別和函式，類別必須定義為 public，物件必須定義為 static public。

    Stream Analytics C sharp function configuration Visual Studio

現有封裝

您可以在任何您選擇的 IDE 中撰寫 .NET Standard UDF，並從 Azure 串流分析查詢中叫用 UDF。 先編譯程式碼並封裝所有的 DLL。 封裝格式的路徑為 /UserCustomCode/CLR/*。 接著，以您的 Azure 儲存體帳戶將 UserCustomCode.zip 上傳至容器的根目錄。

當組件 zip 封裝已上傳到您的 Azure 儲存體帳戶後，您可以使用 Azure 串流分析查詢中的函式。 您只需要在串流分析作業設定中加入儲存體資訊即可。 您無法使用此選項在本機上測試函式，因為 Visual Studio 工具不會下載您的封裝。 系統會直接對服務剖析封裝路徑。

在工作設定檔 JobConfig.json 中設定組件路徑：

展開 [使用者定義的程式碼設定] 區段，然後在設定中填入以下建議的值：

設定 建議的值
全域儲存體設定資源 選擇來自目前帳戶的資料來源
全域儲存體設定訂用帳戶 < 您的訂用帳戶 >
全域儲存體設定儲存體帳戶 < 您的儲存體帳戶 >
自訂程式碼儲存體設定資源 選擇來自目前帳戶的資料來源
自訂程式碼儲存體設定儲存體帳戶 < 您的儲存體帳戶 >
自訂程式碼儲存體設定容器 < 您的儲存體容器 >
自訂程式碼組件來源 來自雲端的現有組件封裝
自訂程式碼組件來源 UserCustomCode.zip

使用者記錄

當作業正在執行時，記錄機制可讓您擷取自訂資訊。 您可以使用記錄資料來即時偵錯或評估自訂程式碼的正確性。

StreamingContext 類別可讓您使用 StreamingDiagnostics.WriteError 函式發佈診斷資訊。 下列程式碼顯示 Azure 串流分析公開的介面。

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 定義 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;
}

StreamingContext 值不需要由 SQL 查詢傳入。 如果輸入參數存在，Azure 串流分析會自動提供內容物件。 MyUdfMethod 的用法不變，如下列查詢所示：

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

您可以透過 診斷記錄存取記錄訊息。

限制

UDF 預覽目前有以下限制：

  • .NET Standard UDF 只能在 Visual Studio Code 或 Visual Studio 中撰寫，並發佈至 Azure。 在 Azure 入口網站的 [函式] 下方，可檢視 .NET Standard UDF 的唯讀版本。 Azure 入口網站不支援撰寫 .NET Standard 函式。

  • 在入口網站中使用 .NET Standard UDF 時，Azure 入口網站查詢編輯器會顯示錯誤。

  • 呼叫外部 REST 端點，例如，進行反向 IP 查詢或從外部來源提取參考資料

  • 由於自訂程式碼會與 Azure 串流分析引擎共用內容，因此自訂程式碼不會參照任何命名空間/dll_name 與 Azure 串流分析程式碼衝突的項目。 例如，您無法參照 Newtonsoft Json。

  • 專案包含的支援檔案會複製到使用者自訂程式碼 ZIP 檔案，您將作業發佈至雲端時會用到此檔案。 解壓縮時，子資料夾中的所有檔案直接複製到雲端的「使用者自訂程式碼」資料夾的根目錄。 ZIP 解壓縮時會「壓平合併」。

  • 使用者自訂程式碼不支援空資料夾。 請勿將空資料夾新增至專案中的支援檔案。

下一步