Membangun fungsi yang ditentukan oleh pengguna .NET Standard untuk proyek Azure Stream Analytics (Pratinjau)

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 memanggil 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 Stream Analytics saat ini dalam pratinjau dan tidak boleh digunakan dalam beban kerja produksi.

Wilayah

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

  • Barat Sentral AS
  • Eropa Utara
  • US Timur
  • US Barat
  • US 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/*. Pustaka Tautan Dinamis (DLL) dan sumber daya disalin dalam folder /UserCustomCode/CLR/*, yang membantu mengisolasi DLL pengguna dari DLL 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 digunakan di C#, nilai tersebut perlu dinaungi dari satu lingkungan ke lingkungan lainnya. Marshaling terjadi untuk semua parameter input UDF. Setiap jenis Azure Stream Analytics memiliki jenis yang sesuai dalam C# yang ditunjukkan pada tabel di bawah ini:

Jenis Azure Stream Analytics Tipe C#
bigint long
float dua kali lipat
nvarchar(maks) string
tanggalwaktu DateTime
Rekaman String kamus<, objek>
Array Objek[]

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

Tipe C# Jenis Azure Stream Analytics
long bigint
dua kali lipat float
string nvarchar(maks)
DateTime tanggalWaktu
struct Rekaman
objek Rekaman
Objek[] Array
String kamus<, objek> 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 dirujuk dalam kueri Azure Stream Analytics. Ini adalah opsi yang direkomendasikan untuk fungsi kompleks yang memerlukan kekuatan penuh bahasa Standar .NET di luar bahasa ekspresinya, seperti logika prosedural atau rekursi. UDF dari proyek lokal mungkin juga 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 komputer lokal Anda.
  2. Tulis kode di kelas Anda. Ingatlah bahwa kelas harus didefinisikan sebagai publik dan 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 perakitan di file konfigurasi pekerjaan, 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 pustaka kelas C# dan ASAUDFDemo adalah proyek Azure Stream Analytics, yang akan mereferensikan CSharpUDFProject.

Proyek Azure Stream Analytics di Visual Studio Code

UDF berikut memiliki fungsi yang mengalikan bilangan bulat dengan sendirinya untuk menghasilkan kuadrat bilangan bulat. Kelas harus didefinisikan sebagai publik dan 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 Anda.

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

    Menambahkan fungsi baru di proyek Azure Stream Analytics

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

    Pilih fungsi CSharp dari proyek Azure Stream Analytics di Visual Studio Code

    Masukkan nama fungsi CSharp di Visual Studio Code

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

    Konfigurasi fungsi C sharp Stream Analytics di VS Code

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

    Konfigurasi fungsi C sharp Azure Stream Analytics

  4. Panggil 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 di 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 dropdown. Biarkan Jalur sebagai default. Langkah ini tidak diperlukan untuk pengujian lokal.

    Pilih jalur pustaka

Mengembangkan UDF di Visual Studio

Ada tiga cara untuk menerapkan 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 mengkompilasi file CodeBehind ke dalam file rakitan. Rakitan dikemas sebagai file zip dan diunggah ke akun penyimpanan Anda ketika Anda mengirimkan pekerjaan Anda ke Azure. Anda dapat mempelajari cara menulis UDF C# menggunakan CodeBehind dengan mengikuti tutorial UDF C# untuk Stream Analytics Edge.

Proyek lokal

Untuk mereferensikan proyek lokal di Visual Studio:

  1. Membuat pustaka kelas standar .NET baru dalam solusi Anda
  2. Tulis kode di kelas Anda. Ingatlah bahwa kelas harus didefinisikan sebagai publik dan objek harus didefinisikan sebagai publik statis.
  3. Bangun proyek Anda. Alat ini akan mengemas semua artefak di folder bin ke file zip dan mengunggah file zip ke akun penyimpanan. Untuk referensi eksternal, gunakan referensi rakitan alih-alih paket NuGet.
  4. Referensikan kelas baru di proyek Azure Stream Analytics Anda.
  5. Tambahkan fungsi baru di proyek Azure Stream Analytics Anda.
  6. Konfigurasikan jalur perakitan dalam file konfigurasi pekerjaan, JobConfig.json. Atur Jalur Rakitan ke Referensi Proyek Lokal atau CodeBehind.
  7. Bangun kembali 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.

Proyek Azure Stream Analytics IoT Edge di Visual Studio

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

    Membangun proyek Azure Stream Analytics IoT Edge di Visual Studio

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

    Menambahkan referensi ke proyek C# di Visual Studio

  3. Pilih nama proyek C# dari daftar.

    Pilih nama proyek C# Anda dari daftar referensi

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

    Menampilkan referensi fungsi yang ditentukan pengguna di penjelajah solusi

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

    Menambahkan item baru ke Functions di solusi Azure Stream Analytics Edge

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

    Pilih fungsi CSharp dari item Stream Analytics Edge di Visual Studio

  7. Klik dua kali fungsi di Penjelajah Solusi untuk membuka dialog konfigurasi.

    Konfigurasi fungsi C sharp di Visual Studio

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

    Konfigurasi fungsi C# untuk Azure Stream Analytics di Visual Studio

Paket yang ada

Anda dapat menulis .NET Standard UDF di IDE pilihan Anda dan memanggilnya dari kueri Azure Stream Analytics Anda. Pertama-tama kompilasi kode Anda dan kemas semua DLL. Format paket memanfaatkan jalur /UserCustomCode/CLR/*. 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 di 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 diurai langsung ke layanan.

Untuk mengonfigurasi jalur perakitan dalam file konfigurasi pekerjaan, JobConfig.json:

Buka bagian Konfigurasi Kode Didefinisikan Pengguna, dan isi konfigurasi dengan nilai-nilai berikut yang disarankan:

Pengaturan Nilai yang Disarankan
Sumber Daya Pengaturan Penyimpanan Global Pilih sumber data dari akun saat ini
Langganan Pengaturan Penyimpanan Global < langganan Anda >
Pengaturan Penyimpanan Global Akun Penyimpanan < akun penyimpanan Anda >
Sumber Daya Pengaturan Penyimpanan Kode Kustom Pilih sumber data dari akun saat ini
Pengaturan Penyimpanan Akun Penyimpanan Kode Kustom < akun penyimpanan Anda >
Wadah Pengaturan Penyimpanan Kode Kustom < kontainer penyimpanan Anda >
Sumber Rakitan Kode Kustom Paket perakitan yang ada dari cloud
Sumber Rakitan Kode Kustom UserCustomCode.zip

Pengelogan pengguna

Mekanisme pengelogan memungkinkan 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 memungkinkan Anda untuk menerbitkan informasi diagnostik menggunakan fungsi StreamingDiagnostics.WriteError. 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, yang 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 digambarkan dalam kueri berikut:

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

Anda dapat mengakses pesan log melalui log diagnostik.

Keterbatasan

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 Functions di portal Microsoft Azure. Penulisan fungsi Standar .NET tidak didukung di portal Microsoft Azure.

  • Editor kueri portal Microsoft Azure menunjukkan 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 layanan/dll_name yang bertentangan 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 di-zip. File zip menjadi "datar" ketika didekompresi.

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

Langkah selanjutnya

  • Last updated on