Azure Stream Analytics'te JavaScript kullanıcı tanımlı işlevleri

Azure Stream Analytics, JavaScript dilinde yazılmış kullanıcı tanımlı işlevleri destekler. JavaScript'in sunduğu zengin String, RegExp, Math, Array ve Date yöntemlerini kullanarak, Stream Analytics işlerinde karmaşık veri dönüşümleri oluşturabilirsiniz. JavaScript kullanıcı tanımlı işlevler, dış bağlantı gerektirmeyen durum bilgisi olmayan, yalnızca işlem tabanlı skaler işlevleri destekler. Bir işlevin dönüş değeri yalnızca skaler (tek) değer olabilir. Bir JavaScript kullanıcı tanımlı işlevini bir işe ekledikten sonra, bu işlevi sorguda yerleşik bir skaler işlev gibi herhangi bir yerde kullanabilirsiniz.

Bu makale, JavaScript kullanıcı tanımlı fonksiyonların ne zaman kullanılacağını ve bunları Stream Analytics işlerinizde nasıl tanımlayıp çağıracağınızı açıklar.

JavaScript kullanıcı tanımlı bir fonksiyon ne zaman kullanılır

JavaScript kullanıcı tanımlı işlevlerini yararlı bulabileceğiniz bazı senaryolar aşağıda verilmiştir:

• Düzenli ifade fonksiyonları kullanılarak dizeleri ayrıştırmak ve manipüle etmek, örneğin Regexp_Replace() ve Regexp_Extract()
• Verilerin kodunu çözme ve kodlama, örneğin ikiliden onaltılıya dönüştürme
• JavaScript Matematik fonksiyonları kullanarak matematiksel hesaplamalar yapmak
• Sıralama, birleştirme, bulma ve doldurma gibi dizi işlemleri gerçekleştirme

İşte Stream Analytics'te JavaScript kullanıcı tanımlı bir fonksiyon kullanarak yapamayacağınız bazı şeyler:

• Örneğin, ters IP araması yapmak veya harici bir kaynaktan referans verisi çekmek gibi harici REST uç noktalarını çağırmak
• Giriş veya çıkışlarda özel olay formatı serileştirme veya serilikten çıkarma işlemi gerçekleştirin
• Özel toplam değerler oluşturma

Date.GetDate() veya Math.random() gibi fonksiyonlar fonksiyon tanımında engellenmemiş olsa da, onları kullanmaktan kaçının. Bu işlevler her çağırdığınızda aynı sonucu döndürmez ve Azure Stream Analytics hizmeti işlev çağrılarının ve döndürülen sonuçların günlüğünü tutmaz. Bir fonksiyon aynı olaylarda farklı bir sonuç döndürürse, siz veya Stream Analytics hizmeti işi yeniden başlattığınızda tekrarlanabilirlik garanti edilmez.

Azure portalında JavaScript kullanıcı tanımlı bir fonksiyon tanımlayın

Bulutta çalışan bir Stream Analytics işi için, Job Topologyaltındaki Functions sayfasından JavaScript kullanıcı tanımlı bir fonksiyon ekleyin; +Ekle menüsünde JavaScript UDF seçeneği bulunur.

Not

Bu deneyim, bulutta çalışacak şekilde yapılandırılmış Stream Analytics işleri için geçerlidir. Stream Analytics işiniz Azure IoT Edge'de çalışacak şekilde yapılandırılmışsa, bunun yerine Visual Studio'yu kullanın ve C# kullanarak kullanıcı tanımlı işlevi yazın.

Bir fonksiyon tanımı aşağıdaki özelliklerden oluşur:

Özellik	Açıklama
İşlev takma adı	Sorunuzdaki fonksiyonu çağıran isim.
Çıkış türü	JavaScript kullanıcı tanımlı işlevinin Stream Analytics sorgunuza döndürdüğü veri türü.
İşlev tanımı	UDF sorgudan her çağrıldığında çalışan JavaScript fonksiyonunuzun uygulanması.

JavaScript UDF mantığı test ve sorun giderme

Stream Analytics portalı, bu kullanıcı tanımlı fonksiyonların mantığını hata ayıklama ve test etmeyi desteklemediği için, JavaScript UDF mantığınızı herhangi bir tarayıcıda test edip hata ayıklayabilir. Fonksiyon beklendiği gibi çalıştığında, Stream Analytics işine eklemeye ve doğrudan sorgunuzdan çağırmaya hazırdır. Ayrıca Stream Analytics for Visual Studio araçlarını kullanarak bir JavaScript UDF ile sorgu mantığınızı test edebilirsiniz.

Stream Analytics, JavaScript çalışma zamanı hatalarını ölümcül olarak görür ve bunları Etkinlik günlüğü aracılığıyla ortaya çıkarır. Günlük, işinizin Aktivite günlüğü sayfasından Azure portalında mevcuttur.

Bir sorguda JavaScript kullanıcı tanımlı işlevi çağırma

JavaScript fonksiyonunuzu sorgunuzda çağırmak için, udf önekiyle birlikte işlev takma adını kullanın. Aşağıdaki örnek, bir Stream Analytics sorgusunda onaltılık değerleri tam sayıya dönüştüren bir JavaScript UDF'sini göstermektedir.

    SELECT
        time,
        UDF.hex2Int(offset) AS IntOffset
    INTO
        output
    FROM
        InputStream

Desteklenen JavaScript nesneleri

Azure Stream Analytics kullanıcı tanımlı JavaScript fonksiyonları, standart, yerleşik JavaScript nesnelerini destekler. Bu nesneler, fonksiyonlarınıza ek yapılandırma olmadan ortak dize, matematik, dizi ve tarih işlemlerine erişim sağlar. Mevcut nesnelerin tam listesi için Küresel Nesneler sayfasına bakınız. Stream Analytics sorgu dili ve JavaScript aynı tür sistemi paylaşmadığı için, Stream Analytics değerleri ikisi arasında geçiş yaparken dönüştürür.

Stream Analytics ve JavaScript tür dönüşümü

Stream Analytics sorgu dili ve JavaScript farklı türleri destekler. Bu tabloda ikisi arasındaki dönüştürme eşlemeleri listelenmektedir:

Stream Analytics	JavaScript
bigint	Sayı (JavaScript yalnızca tam olarak 2^53’e kadar tamsayıları temsil edebilir)
DateTime	Tarih (JavaScript yalnızca milisaniye birimini destekler)
çift	Sayı
nvarchar(MAX)	String
Kayıt	Nesne
Dizi	Dizi
NULL	Boş

JavaScript’ten Stream Analytics’e dönüşümler aşağıda verilmiştir:

JavaScript	Stream Analytics
Sayı	Bigint (sayı yuvarlak ve long.MinValue ile long.MaxValue arasındaysa; aksi takdirde iki katıdır)
Tarih	DateTime
String	nvarchar(MAX)
Nesne	Kaydı başlat
Dizi	Dizi
Null, Tanımsız	NULL
Başka bir tür (örneğin, bir işlev veya hata)	Desteklenmiyor (çalışma zamanı hatası ile sonuçlanır)

JavaScript büyük harf duyarlıdır ve JavaScript kodundaki nesne alanlarının kasası, gelen verideki alanların kasabıyla eşleşmelidir. Uyumluluk seviyesi 1.0'a sahip işler SQL SELECT ifadesinden alanları küçük harflere dönüştürür. Uyumluluk seviyesi 1.1 ve üzerinde, SELECT ifadesindeki alanlar SQL sorgusunda belirtilen aynı kaplanmaya sahiptir.

Yaygın fonksiyon kalıpları

Aşağıdaki kalıplar, JavaScript kullanıcı tanımlı fonksiyonları kullanarak Stream Analytics sorgularınızda veriyi dönüştürmenin yaygın yollarını göstermektedir. Her desen, bir fonksiyon tanımı ve onu çağıran örnek bir sorgu içerir.

Çıktıya iç içe geçmiş JSON yazma

Girdi olarak bir Stream Analytics iş çıktısını kullanan bir takip işleme adımınız varsa ve bir JSON biçimi gerektiriyorsa, çıktıya bir JSON dizesi yazabilirsiniz. Aşağıdaki fonksiyon tanımı, JSON.stringify() fonksiyonunu çağırarak tüm girişin isim/değer çiftlerini paketler ve ardından bunları çıktıda tek bir dizim değeri olarak yazar.

function main(x) {
return JSON.stringify(x);
}

Bir Stream Analytics sorgusu, aşağıdaki örnekte gösterildiği gibi fonksiyonu çağırır.

SELECT
    DataString,
    DataValue,
    HexValue,
    UDF.jsonstringify(input) As InputEvent
INTO
    output
FROM
    input PARTITION BY PARTITIONID

İşlemek için dizeyi JSON nesnesine dönüştür

Eğer JSON olan bir string alanınız varsa ve bunu JavaScript UDF'de işlemek üzere JSON nesnesine dönüştürmek istiyorsanız, JSON.parse() fonksiyonunu kullanarak bir JSON nesnesi oluşturabilir ve sonra bunu kullanabilirsiniz. Aşağıdaki fonksiyon tanımı, diziyi ayrıştırır ve ortaya çıkan nesneden bir özellik döndürür.

function main(x) {
var person = JSON.parse(x);  
return person.name;
}

Bir Stream Analytics sorgusu, aşağıdaki örnekte gösterildiği gibi fonksiyonu çağırır.

SELECT
    UDF.getName(input) AS Name
INTO
    output
FROM
    input

Hata işleme için try/catch kullanma

Deneme/yakalama blokları, JavaScript UDF'ye aktardığınız yanlış biçimlendirilmiş giriş verileriyle ilgili sorunları tespit etmenize yardımcı olabilir. Aşağıdaki fonksiyon tanımı, ayrıştırma hatalarını yönetmek için deneme/yakalama bloğu kullanır.

function main(input, x) {
    var obj = null;

    try{
        obj = JSON.parse(x);
    }catch(error){
        throw input;
    }
    
    return obj.Value;
}

Aşağıdaki örnek sorguda, tüm kaydı ilk parametre olarak iletiyorsunuz, böylece fonksiyon hata olursa onu döndürebilir.

SELECT
    A.context.company AS Company,
    udf.getValue(A, A.context.value) as Value
INTO
    output
FROM
    input A

toLocaleString()

JavaScript'teki toLocaleString yöntemi, metodu çağırdığınız tarih-saat verilerini temsil eden dil-duyarlı bir diziyi döndürür. Azure Stream Analytics sistem zaman damgası olarak sadece UTC tarih-saatini kabul etse de, bu yöntemi kullanarak sistem zaman damgasını başka bir yerel ve saat dilimine dönüştürebilirsiniz. Bu yöntem, Internet Explorer'da sunulan uygulama davranışıyla aynı davranışı takip eder. Aşağıdaki fonksiyon tanımı, giriş tarih saatini de-DE konumuna dönüştürür.

function main(datetime){
    const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
    return datetime.toLocaleDateString('de-DE', options);
}

Aşağıdaki örnek sorguda, giriş değeri olarak bir datetime iletilir.

SELECT
    udf.toLocaleString(input.datetime) as localeString
INTO
    output
FROM
    input

Bu sorgunun çıktısı, belirtilen seçeneklerle de-DE biçimindeki giriş tarih ve saatidir.

Samstag, 28. December 2019

Kullanıcı günlüğü

Log, Azure Stream Analytics'in bir iş çalışırken JavaScript kullanıcı tanımlı bir fonksiyondan özel bilgileri yakalamak için kullandığı mekanizmadır. Çalışan bir işin iç işleyişi başka türlü doğrudan görülemediğinden, günlük verileri özel kodunuzun davranışı ve doğruluğu hakkında size gerçek zamanlı görünürlük sağlar. Her günlük mesajı, mesajın ne kadar önemli olduğunu ve işin devam edip edemeyeceğini gösteren bir olay seviyesi taşır.

Bilgilendirici mesajlar console.info() yönteminden gelir, örneğin console.info('my info message');. Bu seviye, yürütme sırasında genel bilgileri kaydeder ve hesaplamayı kesintiye uğratmaz. Uyarı mesajları console.warn() yönteminden gelir, örneğin console.warn('my warning message');. Bu seviye, beklenmedik olabilecek ama hesaplama için kabul edilebilir olan verileri kaydeder, böylece iş çalışmaya devam eder. Hata mesajları konsol.error() ve console.log() yöntemlerinden gelir, örneğin console.error('my error message');. Bu yöntemler yalnızca kodun devam edemediği durumlarda geçerlidir, bu yüzden verilen hata bilgisiyle bir istisna oluşturur ve iş durdurulur.

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

atob() ve btoa()

Stream Analytics, ikili veriyi metin olarak kodlamanın yaygın bir yolu olan Base64 dönüştürme için iki yöntemi destekler. btoa() yöntemi, bir ASCII dizesini Base64'e kodlar, atob() yöntemi ise Base64 ile kodlanmış veri dizesini tekrar bir ASCII dizesine çözer. Aşağıdaki örnekte, btoa() bir ASCII dizesini kodlar ve ardından atob() sonucu yeniden özgün dizeye çözer.

var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);

İlgili içerik

• Makine öğrenimi UDF
• C# kullanıcı tanımlı fonksiyonlar