Mengembangkan fungsi .NET Standard untuk pekerjaan Azure Stream Analytics (Pratinjau)

  • Artikel

Penting

Fungsi yang ditentukan pengguna .Net Standard untuk Azure Stream Analytics akan dihentikan pada 30 September 2024. Setelah tanggal tersebut, tidak akan mungkin untuk menggunakan fitur tersebut. Silakan transisi ke fungsi yang ditentukan pengguna JavaScript untuk Azure Stream Analytics.

Azure Stream Analytics menawarkan bahasa kueri seperti SQL untuk melakukan transformasi dan komputasi melalui aliran data peristiwa. Ada banyak fungsi bawaan, tetapi beberapa skenario kompleks membutuhkan fleksibilitas tambahan. Dengan fungsi yang ditentukan pengguna (UDF) .NET Standard, Anda dapat menggunakan fungsi Anda sendiri yang ditulis dalam bahasa standar .NET (C#, F#, dll.) untuk memperluas bahasa kueri Azure Stream Analytics. UDF memungkinkan Anda melakukan komputasi matematika yang kompleks, mengimpor model ML kustom menggunakan ML.NET, dan menggunakan logika imputasi kustom untuk data yang hilang. Fitur UDF untuk pekerjaan Analisis Aliran saat ini dalam pratinjau dan tidak boleh digunakan dalam beban kerja produksi.

Wilayah

Fitur fungsi yang ditentukan pengguna .NET diaktifkan untuk pekerjaan cloud yang berjalan di kluster Azure Stream Analytics. Pekerjaan yang berjalan di SKU multi-penyewa Standar dapat memanfaatkan fitur ini di wilayah publik berikut:

  • AS Tengah Bagian Barat
  • Eropa Utara
  • AS Timur
  • US Barat
  • AS Timur 2
  • Eropa Barat

Jika Anda tertarik menggunakan fitur ini di wilayah lain, Anda dapat meminta akses.

Jalur paket

Format paket UDF apa pun memiliki jalur /UserCustomCode/CLR/*. Dynamic-link library (DLL) dan sumber daya disalin di bawah folder /UserCustomCode/CLR/*, yang membantu mengisolasi DLL dari sistem dan DLL Azure Stream Analytics. Jalur paket ini digunakan untuk semua fungsi terlepas dari metode yang digunakan untuk menggunakannya.

Jenis dan pemetaan yang didukung

Agar nilai Azure Stream Analytics dapat digunakan dalam C#, nilai tersebut perlu disusun dari satu lingkungan ke lingkungan lainnya. Penyusunan terjadi untuk semua parameter input UDF. Setiap jenis Azure Stream Analytics memiliki jenis terkait di C# yang diperlihatkan pada tabel di bawah ini:

Jenis Azure Stream Analytics Jenis C#
bigint long
float ganda
nvarchar(maks) string
datetime DateTime
Rekaman Dictionary<string, object>
Array Objek[]

Hal yang sama berlaku ketika data perlu disusu dari C# ke Azure Stream Analytics, yang mana terjadi pada nilai output UDF. Tabel di bawah ini memperlihatkan jenis apa saja yang didukung:

Jenis C# Jenis Azure Stream Analytics
long bigint
ganda float
string nvarchar(maks)
DateTime tanggalWaktu
struktur Rekaman
object Rekaman
Objek[] Array
Dictionary<string, object> Rekaman

Mengembangkan UDF di Visual Studio Code

Alat Visual Studio Code untuk Azure Stream Analytics memudahkan Anda menulis UDF, menguji pekerjaan Anda secara lokal (bahkan offline), dan menerbitkan pekerjaan Azure Stream Analytics Anda ke Azure.

Ada dua cara untuk menerapkan UDF standar .NET di alat Visual Studio Code.

  • UDF dari DLL lokal
  • UDF dari proyek lokal

Proyek lokal

Fungsi yang ditentukan pengguna dapat ditulis dalam rakitan yang kemudian direferensikan dalam kueri Azure Stream Analytics. Ini adalah opsi yang direkomendasikan untuk fungsi kompleks yang memerlukan kekuatan penuh dari bahasa .NET Standard di luar bahasa ekspresinya, seperti logika prosedural atau rekursi. UDF dari proyek lokal juga dapat digunakan saat Anda perlu berbagi logika fungsi di beberapa kueri Azure Stream Analytics. Menambahkan UDF ke proyek lokal memberi Anda kemampuan untuk men-debug dan menguji fungsi Anda secara lokal.

Untuk mereferensikan proyek lokal:

  1. Buat pustaka kelas standar .NET baru di mesin lokal Anda.
  2. Tulis kode di kelas Anda. Semua kelas harus didefinisikan sebagai publik, dan semua objek harus didefinisikan sebagai publik statis.
  3. Tambahkan file konfigurasi Fungsi CSharp baru di proyek Azure Stream Analytics Anda dan referensikan proyek Pustaka kelas CSharp.
  4. Konfigurasikan jalur rakitan dalam file konfigurasi pekerjaan,bagian JobConfig.json, bagian CustomCodeStorage. Langkah ini tidak diperlukan untuk pengujian lokal.

DLL Lokal

Anda juga dapat mereferensikan DLL lokal yang menyertakan fungsi yang ditentukan pengguna.

Contoh

Dalam contoh ini, CSharpUDFProject adalah proyek perpustakaan kelas C# dan ASAUDFDemo adalah proyek Azure Stream Analytics, yang akan mereferensikan CSharpUDFProject.

Azure Stream Analytics project in Visual Studio Code

UDF berikut ini memiliki fungsi yang mengalikan bilangan bulat dengan sendirinya untuk menghasilkan kuadrat bilangan bulat. Semua kelas harus didefinisikan sebagai publik dan semua objek harus didefinisikan sebagai publik statis.

using System;

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

Langkah-langkah berikut menunjukkan cara menambahkan fungsi C# UDF ke proyek Azure Stream Analytics.

  1. Klik kanan pada folder Fungsi dan pilih Tambahkan Item.

    Add new function in Azure Stream Analytics project

  2. Tambahkan fungsi C# SquareFungsi ke proek Azure Stream Analytics Anda.

    Select CSharp function from Stream Analytics project in VS Code

    Enter CSharp function name in VS Code

  3. Di konfigurasi fungsi C#, pilihlah Pilih jalur proyek pustaka untuk memilih proyek C# Anda dari daftar menurun dan pilih Bangun proyek untuk membangun proyek Anda. Lalu pilihlah Pilih kelas dan Pilih metode untuk memilih nama kelas dan metode terkait dari daftar menurun. Untuk merujuk ke metode, jenis, dan fungsi dalam kueri Azure Stream Analytics, kelas harus didefinisikan sebagai publik dan objek harus didefinisikan sebagai publik statis.

    Stream Analytics C sharp function configuration VS Code

    Jika Anda ingin menggunakan UDF C# dari DLL, pilihlah Pilih jalur dll pustaka untuk memilih DLL. Lalu pilihlah Pilih kelas dan Pilih metode untuk memilih nama kelas dan metode terkait dari daftar menurun.

    Stream Analytics C sharp function configuration

  4. Gunakan UDF di kueri Azure Stream Analytics Anda.

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

  5. Sebelum mengirimkan pekerjaan ke Azure, konfigurasikan jalur paket dalam file konfigurasi pekerjaan, JobConfig.json, bagian CustomCodeStorage. Gunakan Pilih dari langganan Anda di CodeLens untuk memilih Langganan Anda dan pilih akun penyimpanan dan nama kontainer dari daftar menurun. Tinggalkan Jalur sebagai default. Langkah ini tidak diperlukan untuk pengujian lokal.

    Choose library path

Mengembangkan UDF di Visual Studio Code

Ada tiga cara untuk mengimplementasikan UDF di alat Visual Studio.

  • File CodeBehind dalam proyek ASA
  • UDF dari proyek lokal
  • Paket yang sudah ada dari akun penyimpanan Azure

CodeBehind

Anda dapat menulis fungsi yang ditentukan pengguna di CodeBehind Script.asql. Alat Visual Studio akan secara otomatis mengompilasi file CodeBehind ke dalam file rakitan. Rakitan dikemas sebagai file zip dan diunggah ke akun penyimpanan Anda saat Anda mengirimkan pekerjaan Anda ke Azure. Anda dapat mempelajari cara menulis C # UDF menggunakan CodeBehind dengan mengikuti tutorial pekerjaan C # UDF untuk Analisis Aliran Azure Stack Edge.

Proyek lokal

Untuk mereferensikan proyek lokal di Visual Studio:

  1. Buat pustaka kelas standar .NET baru di solusi Anda
  2. Tulis kode di kelas Anda. Semua kelas harus didefinisikan sebagai publik, dan semua objek harus didefinisikan sebagai publik statis.
  3. Bangun proyek Anda. Alat akan mengemas semua artefak di folder bin ke file zip dan mengunggah file zip ke akun penyimpanan. Untuk referensi eksternal, gunakan referensi rakitan dibandingkan dengan paket NuGet.
  4. Referensi kelas baru di proyek Azure Stream Analytics Anda.
  5. Tambahkan fungsi baru dalam proyek Azure Stream Analytics.
  6. Konfigurasikan jalur rakitan dalam file konfigurasi pekerjaan, JobConfig.json. Atur Jalur Rakitan ke Referensi Proyek Lokal atau CodeBehind.
  7. Bangun ulang proyek fungsi dan proyek Azure Stream Analytics.

Contoh

Dalam contoh ini, UDFTest adalah proyek pustaka kelas C# dan ASAUDFDemo adalah proyek Azure Stream Analytics, yang akan mereferensikan UDFTest.

Azure Stream Analytics IoT Edge project in Visual Studio

  1. Bangun project C# Anda, yang akan memungkinkan Anda menambahkan referensi ke UDF C# Anda dari kueri Azure Stream Analytics.

    Build an Azure Stream Analytics IoT Edge project in Visual Studio

  2. Tambahkan referensi ke proyek C# dalam proyek ASA. Klik kanan simpul Referensi dan pilih Tambahkan Referensi.

    Add a reference to a C# project in Visual Studio

  3. Pilih nama proyek C# dari daftar.

    Choose your C# project name from the reference list

  4. Anda akan melihat UDFTest tercantum di bawah Referensi di Penjelajah Solusi.

    View the user defined function reference in solution explorer

  5. Klik kanan pada folder Fungsi dan pilih Item Baru.

    Add new item to Functions in Azure Stream Analytics Edge solution

  6. Tambahkan fungsi C# SquareFunction.json ke proyek Azure Stream Analytics Anda.

    Select CSharp function from Stream Analytics Edge items in Visual Studio

  7. Klik ganda fungsi di Penjelajah Solusi untuk membuka dialog konfigurasi.

    C sharp function configuration in Visual Studio

  8. Dalam konfigurasi fungsi C#, pilih Muat dari Referensi Proyek ASA dan rakitan, kelas, dan nama metode terkait dari daftar menurun. Untuk merujuk ke metode, jenis, dan fungsi dalam kueri Azure Stream Analytics, kelas harus didefinisikan sebagai publik dan objek harus didefinisikan sebagai publik statis.

    Stream Analytics C sharp function configuration Visual Studio

Paket yang ada

Anda dapat menulis .NET Standard UDF di IDE apa pun pilihan Anda dan memanggilnya dari kueri Azure Stream Analytics Anda. Pertama-tama kompilasikan kode dan paket Anda ke semua DLL. Format paket memiliki /UserCustomCode/CLR/* jalur. Kemudian, unggah UserCustomCode.zip ke akar kontainer di akun penyimpanan Azure Anda.

Setelah paket zip rakitan diunggah ke akun penyimpanan Azure, Anda dapat menggunakan fungsi tersebut dalam kueri Azure Stream Analytics. Yang perlu Anda lakukan adalah menyertakan informasi penyimpanan dalam konfigurasi pekerjaan Azure Stream Analytics. Anda tidak dapat menguji fungsi secara lokal dengan opsi ini karena alat Visual Studio tidak akan mengunduh paket Anda. Jalur paket diuraikan langsung ke layanan.

Konfigurasikan jalur rakitan dalam file konfigurasi pekerjaan, JobConfig.json:

Perluas bagian Konfigurasi Kode yang Ditentukan Pengguna, dan isi konfigurasi dengan nilai yang disarankan berikut ini:

Pengaturan Nilai yang disarankan
Sumber Daya Pengaturan Azure Storage Global Pilih sumber data dari akun saat ini
Langganan Pengaturan Penyimpanan Global < langganan Anda >
Akun Penyimpanan Pengaturan Penyimpanan Global < akun penyimpanan Anda >
Sumber Daya Pengaturan Azure Storage Kode Kustom Pilih sumber data dari akun saat ini
Akun Storage Pengaturan Azure Storage Kode Kustom < akun penyimpanan Anda >
Kontainer Pengaturan Azure Storage Kode Kustom < kontainer penyimpanan Anda>
Sumber Rakitan Kode Kustom Paket rakitan yang ada dari cloud
Sumber Rakitan Kode Kustom UserCustomCode.zip

Pengelogan Pengguna

Mekanisme pengelogan menginzinkan Anda untuk mengambil informasi kustom saat pekerjaan sedang berjalan. Anda dapat menggunakan data log untuk men-debug atau menilai kebenaran kode kustom secara real time.

Kelas StreamingContext ini memungkinkan Anda menerbitkan informasi diagnostik menggunakan fungsi StreamingDiagnostics.WriteError tersebut. Kode di bawah ini menunjukkan antarmuka yang diekspos oleh 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 diteruskan sebagai parameter input ke metode UDF dan dapat digunakan dalam UDF untuk menerbitkan informasi log kustom. Dalam contoh di bawah ini, MyUdfMethod mendefinisikan input data, yang disediakan oleh kueri, dan input konteks sebagai StreamingContext, disediakan oleh mesin runtime.

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

Nilai StreamingContext tidak perlu diteruskan oleh kueri SQL. Azure Stream Analytics menyediakan objek konteks secara otomatis jika parameter input ada. Penggunaan MyUdfMethod tidak berubah, seperti yang diperlihatkan dalam kueri berikut ini:

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

Anda dapat mengakses pesan log melalui log diagnostik.

Batasan

Pratinjau UDF saat ini memiliki batasan berikut:

  • .NET Standard UDF hanya dapat ditulis di Visual Studio Code atau Visual Studio dan diterbitkan ke Azure. Versi baca-saja dari .NET Standard UDF dapat dilihat di bawah Fungsi di portal Microsoft Azure. Penulisan fungsi .NET Standard tidak didukung di portal Microsoft Azure.

  • Editor kueri portal Microsoft Azure memperlihatkan kesalahan saat menggunakan .NET Standard UDF di portal.

  • Memanggil titik akhir REST eksternal, misalnya, melakukan pencarian IP terbalik atau menarik data referensi dari sumber eksternal

  • Karena kode kustom berbagi konteks dengan mesin Azure Stream Analytics, kode kustom tidak dapat mereferensikan apa pun yang memiliki namespace/dll_name yang berkonflik dengan kode Azure Stream Analytics. Misalnya, Anda tidak dapat mereferensikan Newtonsoft Json.

  • File pendukung yang disertakan dalam proyek disalin ke file zip Kode Kustom Pengguna yang digunakan saat Anda menerbitkan pekerjaan ke cloud. Semua file dalam subfolder disalin langsung ke akar folder Kode Kustom Pengguna di cloud saat zip file dibuka. Zip "diratakan" saat didekompresi.

  • Kode Kustom Pengguna tidak mendukung folder kosong. Jangan tambahkan folder kosong ke berkas pendukung dalam proyek.

Langkah berikutnya