Azure Stream Analytics işleri için .NET Standard kullanıcı tanımlı işlevler geliştirme (Önizleme)

Önemli

Azure Stream Analytics için .Net Standard kullanıcı tanımlı işlevler 30 Eylül 2024'te kullanımdan kaldırılacaktır. Bu tarihten sonra özelliği kullanmak mümkün olmayacaktır. Lütfen Azure Stream Analytics için JavaScript kullanıcı tanımlı işlevlerine geçin.

Azure Stream Analytics, olay verisi akışları üzerinde dönüştürmeler ve hesaplamalar gerçekleştirmek için SQL benzeri bir sorgu dili sunar. Birçok yerleşik işlev vardır, ancak bazı karmaşık senaryolar ek esneklik gerektirir. .NET Standart kullanıcı tanımlı işlevlerle (UDF), Stream Analytics sorgu dilini genişletmek için herhangi bir .NET standart dilinde (C#, F# vb.) yazılmış kendi işlevlerinizi çağırabilirsiniz. UDF'ler karmaşık matematik hesaplamaları gerçekleştirmenize, ML.NET kullanarak özel ML modellerini içeri aktarmanıza ve eksik veriler için özel imputation mantığı kullanmanıza olanak tanır. Stream Analytics işleri için UDF özelliği şu anda önizleme aşamasındadır ve üretim iş yüklerinde kullanılmamalıdır.

Bölgeler

.NET kullanıcı tanımlı işlev özelliği, Stream Analytics kümelerinde çalışan bulut işleri için etkinleştirilir. Standart çok kiracılı SKU'da çalışan işler aşağıdaki genel bölgelerde bu özelliği kullanabilir:

• Batı Orta ABD
• Kuzey Avrupa
• Doğu ABD
• Batı ABD
• Doğu ABD 2
• West Europe

Bu özelliği başka bir bölgede kullanmak istiyorsanız erişim isteyebilirsiniz.

Paket yolu

Herhangi bir UDF paketinin biçiminde yolu /UserCustomCode/CLR/*bulunur. Dinamik Bağlantı Kitaplıkları (DLL'ler) ve kaynaklar klasörün altına /UserCustomCode/CLR/* kopyalanır ve bu da kullanıcı DLL'lerini sistemden ve Azure Stream Analytics DLL'lerinden yalıtmalarına yardımcı olur. Bu paket yolu, bunları kullanmak için kullanılan yöntemden bağımsız olarak tüm işlevler için kullanılır.

Desteklenen türler ve eşleme

C# dilinde kullanılacak Azure Stream Analytics değerlerinin bir ortamdan diğerine sıralanması gerekir. Hazırlama, UDF'nin tüm giriş parametreleri için gerçekleşir. Her Azure Stream Analytics türünün C# dilinde karşılık gelen bir türü aşağıdaki tabloda gösterilmiştir:

Azure Stream Analytics türü	C# türü
bigint	uzun
kayan noktalı sayı	çift
nvarchar(max)	Dize
datetime	DateTime
Kaydet	Sözlük<dizesi, nesne>
Dizi	Nesne[]

Verilerin C# dilinden Azure Stream Analytics'e sıralanması gerektiğinde de aynı durum geçerlidir ve bu durum UDF'nin çıkış değerinde gerçekleşir. Aşağıdaki tabloda hangi türlerin desteklendiği gösterilmektedir:

C# türü	Azure Stream Analytics türü
uzun	bigint
çift	kayan noktalı sayı
Dize	nvarchar(max)
DateTime	tarih saat
struct	Kaydet
nesne	Kaydet
Nesne[]	Dizi
Sözlük<dizesi, nesne>	Kaydet

Visual Studio Code'da UDF geliştirme

Azure Stream Analytics için Visual Studio Code araçları UDF yazmanızı, işlerinizi yerel ortamda (hatta çevrimdışı) test etmenizi ve Stream Analytics işinizi Azure'da yayımlamanızı kolaylaştırır.

Visual Studio Code araçlarında .NET standart UDF'lerini uygulamanın iki yolu vardır.

• Yerel DLL'lerden UDF
• Yerel projeden UDF

Yerel proje

Kullanıcı tanımlı işlevler, daha sonra bir Azure Stream Analytics sorgusunda başvurulabilecek bir derlemede yazılabilir. Bu, yordamsal mantık veya özyineleme gibi ifade dilinin ötesinde bir .NET Standart dilinin tam gücünü gerektiren karmaşık işlevler için önerilen seçenektir. İşlev mantığını birkaç Azure Stream Analytics sorgusunda paylaşmanız gerektiğinde yerel projedeki UDF'ler de kullanılabilir. Yerel projenize UDF'ler eklemek, işlevlerinizin hatalarını ayıklamanızı ve işlevlerinizi yerel olarak test edebilmenizi sağlar.

Yerel projeye başvurmak için:

1. Yerel makinenizde yeni bir .NET standart sınıf kitaplığı oluşturun.
2. Kodu sınıfınıza yazın. Sınıfların genel ve nesnelerin statik genel olarak tanımlanması gerektiğini unutmayın.
3. Azure Stream Analytics projenize yeni bir CSharp İşlevi yapılandırma dosyası ekleyin ve CSharp sınıf kitaplığı projesine başvurun.
4. İş yapılandırma dosyasında, JobConfig.jsonCustomCode Depolama bölümünde derleme yolunu yapılandırın. Bu adım yerel test için gerekli değildir.

Yerel DLL'ler

Kullanıcı tanımlı işlevleri içeren yerel DLL'lere de başvurabilirsiniz.

Örnek

Bu örnekte CSharpUDFProject bir C# sınıf kitaplığı projesidir ve ASAUDFDemo da CSharpUDFProject'e başvuruda bulunan Azure Stream Analytics projesidir.

Aşağıdaki UDF, tamsayı karesini üretmek için bir tamsayıyı tek başına çarpan bir işleve sahiptir. Sınıflar genel olarak tanımlanmalı ve nesneler statik genel olarak tanımlanmalıdır.

using System;

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

Aşağıdaki adımlarda Stream Analytics projenize C# UDF işlevinin nasıl ekleneceği gösterilmektedir.

1. İşlevler klasörüne sağ tıklayın ve Öğe Ekle'yi seçin.

   

2. Azure Stream Analytics projenize bir C# işlevi SquareFunction ekleyin.

   

   

3. C# işlevi yapılandırmasında Kitaplık proje yolunu seçin'i seçerek açılan listeden C# projenizi seçin ve projenizi oluşturmak için Proje oluştur'u seçin. Ardından, açılan listeden ilgili sınıf ve yöntem adını seçmek için Sınıf seç ve Yöntemi seç'i seçin. Stream Analytics sorgusundaki yöntemlere, türlere ve işlevlere başvurmak için sınıfların genel ve nesnelerin statik ortak olarak tanımlanması gerekir.

   

   DLL'den C# UDF kullanmak istiyorsanız, DLL'yi seçmek için Kitaplık dll yolunu seçin'i seçin. Ardından, açılan listeden ilgili sınıf ve yöntem adını seçmek için Sınıf seç ve Yöntemi seç'i seçin.

   

4. Azure Stream Analytics sorgunuzda UDF'yi çağırın.

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

5. İşi Azure'a göndermeden önce , CustomCode Depolama iş yapılandırma dosyasındaki JobConfig.jsonpaket yolunu yapılandırın. CodeLens'te Aboneliğinizden seç'i kullanarak Aboneliğinizi seçin ve açılan listeden depolama hesabını ve kapsayıcı adını seçin. Yolu varsayılan olarak bırakın. Bu adım yerel test için gerekli değildir.

   

Visual Studio'da UDF geliştirme

Visual Studio araçlarında UDF'leri uygulamanın üç yolu vardır.

• ASA projesinde CodeBehind dosyaları
• Yerel projeden UDF
• Azure depolama hesabından mevcut bir paket

CodeBehind

Script.asql CodeBehind içinde kullanıcı tanımlı işlevler yazabilirsiniz. Visual Studio araçları CodeBehind dosyasını otomatik olarak bir derleme dosyasına derler. Derlemeler zip dosyası olarak paketlenir ve işinizi Azure'a gönderdiğinizde depolama hesabınıza yüklenir. Stream Analytics Edge işleri için C# UDF öğreticisini izleyerek CodeBehind kullanarak C# UDF yazmayı öğrenebilirsiniz.

Yerel proje

Visual Studio'da yerel projeye başvurmak için:

1. Çözümünüzde yeni bir .NET standart sınıf kitaplığı oluşturma
2. Kodu sınıfınıza yazın. Sınıfların genel ve nesnelerin statik genel olarak tanımlanması gerektiğini unutmayın.
3. Projenizi derleyin. Araçlar, bin klasöründeki tüm yapıtları bir zip dosyasına paketleyip zip dosyasını depolama hesabına yükler. Dış başvurular için NuGet paketi yerine derleme başvurusu kullanın.
4. Azure Stream Analytics projenizdeki yeni sınıfa başvurun.
5. Azure Stream Analytics projenize yeni bir işlev ekleyin.
6. İş yapılandırma dosyasında derleme yolunu yapılandırın. JobConfig.json Derleme Yolunu Yerel Proje Başvurusu veya CodeBehind olarak ayarlayın.
7. Hem işlev projesini hem de Azure Stream Analytics projesini yeniden oluşturun.

Örnek

Bu örnekte UDFTest bir C# sınıf kitaplığı projesidir ve ASAUDFDemo da UDFTest'e başvuracak olan Azure Stream Analytics projesidir.

1. Azure Stream Analytics sorgusundan C# UDF'nize başvuru eklemenize olanak tanıyan C# projenizi oluşturun.

   

2. ASA projesindeki C# projesine başvuruyu ekleyin. Başvurular düğümüne sağ tıklayın ve Başvuru Ekle'yi seçin.

   

3. Listeden C# proje adını seçin.

   

4. Çözüm Gezgini'de Başvurular altında UDFTest'in listelendiğini görmeniz gerekir.

   

5. İşlevler klasörüne sağ tıklayın ve Yeni Öğe'yi seçin.

   

6. Azure Stream Analytics projenize bir C# işlevi SquareFunction.json ekleyin.

   

7. yapılandırma iletişim kutusunu açmak için Çözüm Gezgini işlevine çift tıklayın.

   

8. C# işlevi yapılandırmasında ASA Proje Başvurusu'ndan yükle'yi ve açılan listeden ilgili derleme, sınıf ve yöntem adlarını seçin. Stream Analytics sorgusundaki yöntemlere, türlere ve işlevlere başvurmak için sınıfların genel ve nesnelerin statik ortak olarak tanımlanması gerekir.

   

Mevcut paketler

İstediğiniz herhangi bir IDE'de .NET Standart UDF'leri yazabilir ve bunları Azure Stream Analytics sorgunuzdan çağırabilirsiniz. İlk olarak kodunuzu derleyin ve tüm DLL'leri paketleyin. Paketin biçiminde yolu /UserCustomCode/CLR/*bulunur. Ardından Azure depolama hesabınızdaki kapsayıcının köküne yükleyin UserCustomCode.zip .

Derleme zip paketleri Azure depolama hesabınıza yüklendikten sonra Azure Stream Analytics sorgularındaki işlevleri kullanabilirsiniz. Tek yapmanız gereken Stream Analytics iş yapılandırmasındaki depolama bilgilerini eklemektir. Visual Studio araçları paketinizi indirmediğinden, işlevi bu seçenekle yerel olarak test yapamazsınız. Paket yolu doğrudan hizmete ayrıştırılır.

İş yapılandırma dosyasında derleme yolunu yapılandırmak için: JobConfig.json

Kullanıcı Tanımlı Kod Yapılandırması bölümünü genişletin ve yapılandırmaya aşağıdaki önerilen değerleri ekleyin:

Ayar	Önerilen Değer
Genel Depolama Ayarlar Kaynağı	Geçerli hesaptaki veri kaynağını seçin
Genel Depolama Ayarlar Aboneliği	< aboneliğiniz >
Genel Depolama Ayarlar Depolama Hesabı	< depolama hesabınız >
Özel Kod Depolama Ayarlar Kaynağı	Geçerli hesaptaki veri kaynağını seçin
Özel Kod Depolama Ayarlar Depolama Hesabı	< depolama hesabınız >
Özel Kod Depolama Ayarlar Kapsayıcısı	< depolama kapsayıcınız >
Özel Kod Derleme Kaynağı	Buluttan mevcut derleme paketleri
Özel Kod Derleme Kaynağı	UserCustomCode.zip

Kullanıcı günlüğü

Günlük mekanizması, bir iş çalışırken özel bilgileri yakalamanıza olanak tanır. Günlük verilerini kullanarak özel kodun hatalarını gerçek zamanlı olarak ayıklayabilir veya doğru şekilde değerlendirebilirsiniz.

sınıfı, StreamingContext işlevini kullanarak StreamingDiagnostics.WriteError tanılama bilgilerini yayımlamanıza olanak tanır. Aşağıdaki kod, Azure Stream Analytics tarafından kullanıma sunulan arabirimi gösterir.

public abstract class StreamingContext
{
    public abstract StreamingDiagnostics Diagnostics { get; }
}

public abstract class StreamingDiagnostics
{
    public abstract void WriteError(string briefMessage, string detailedMessage);
}

StreamingContext UDF yöntemine giriş parametresi olarak geçirilir ve özel günlük bilgilerini yayımlamak için UDF içinde kullanılabilir. Aşağıdaki örnekte, MyUdfMethod sorgu tarafından sağlanan bir veri girişini ve çalışma zamanı altyapısı tarafından sağlanan olarak StreamingContextbağlam girişini tanımlar.

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

Değerin StreamingContext SQL sorgusu tarafından geçirilmesi gerekmez. Azure Stream Analytics, giriş parametresi varsa otomatik olarak bir bağlam nesnesi sağlar. MyUdfMethod kullanımı, aşağıdaki sorguda gösterildiği gibi değişmez:

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

Tanılama günlükleri aracılığıyla günlük iletilerine erişebilirsiniz.

Sınırlamalar

UDF önizlemesinde şu anda aşağıdaki sınırlamalar vardır:

• .NET Standart UDF'leri yalnızca Visual Studio Code veya Visual Studio'da yazılabilir ve Azure'da yayımlanabilir. .NET Standart UDF'lerinin salt okunur sürümleri Azure portalındaki İşlevler altında görüntülenebilir. .NET Standard işlevlerinin yazılması Azure portalında desteklenmez.

• Azure portalı sorgu düzenleyicisi portalda .NET Standard UDF kullanılırken bir hata gösterir.

• Dış REST uç noktalarını çağırma, örneğin ters IP araması yapma veya dış kaynaktan başvuru verilerini çekme

• Özel kod, Azure Stream Analytics altyapısıyla bağlamı paylaştığından özel kod, Azure Stream Analytics koduyla çakışan ad alanına/dll_name sahip hiçbir şeye başvuramaz. Örneğin, Newtonsoft Json'a başvuramazsınız.

• Projeye dahil edilen destekleyici dosyalar, işi bulutta yayımladığınızda kullanılan Kullanıcı Özel Kodu zip dosyasına kopyalanır. Alt klasörlerdeki tüm dosyalar, sıkıştırması açıldığında doğrudan buluttaki Kullanıcı Özel Kodu klasörünün köküne kopyalanır. Sıkıştırması açıldığında zip "düzleştirilmiş" olur.

• Kullanıcı Özel Kodu boş klasörleri desteklemez. Projedeki destekleyici dosyalara boş klasörler eklemeyin.

Sonraki adımlar

• Öğretici: Azure Stream Analytics işi için C# kullanıcı tanımlı işlev yazma (Önizleme)
• Öğretici: Azure Stream Analytics JavaScript kullanıcı tanımlı işlevleri
• Visual Studio Code'da Azure Stream Analytics işi oluşturma