Fungsi yang ditentukan pengguna JavaScript di Azure Stream Analytics

Azure Stream Analytics mendukung fungsi yang ditentukan pengguna yang ditulis dalam JavaScript. Dengan menggunakan seperangkat metode String, RegExp, Math, Array, dan Date yang kaya yang disediakan JavaScript, Anda dapat membuat transformasi data kompleks dalam pekerjaan Stream Analytics. Fungsi JavaScript yang ditentukan pengguna mendukung fungsi skalar nirstatus yang hanya untuk komputasi dan tidak memerlukan konektivitas eksternal. Nilai kembali fungsi hanya dapat menjadi nilai skalar (tunggal). Setelah Anda menambahkan fungsi yang ditentukan pengguna JavaScript ke pekerjaan, Anda bisa menggunakan fungsi di mana saja dalam kueri, seperti fungsi bernilai skalar bawaan.

Artikel ini menjelaskan kapan menggunakan fungsi yang didefinisikan pengguna JavaScript dan cara mendefinisikan serta memanggilnya dalam pekerjaan Stream Analytics Anda.

Kapan menggunakan fungsi yang didefinisikan pengguna JavaScript

Berikut adalah beberapa skenario di mana fungsi yang ditentukan pengguna JavaScript berguna bagi Anda:

  • Mengurai dan memanipulasi string menggunakan fungsi ekspresi reguler, misalnya Regexp_Replace() dan Regexp_Extract()
  • Mendekodekan dan mengodekan data, misalnya, konversi biner-ke-hex
  • Melakukan perhitungan matematis dengan menggunakan fungsi JavaScript Math
  • Melakukan operasi array seperti mengurutkan, menggabungkan, menemukan, dan mengisi

Berikut beberapa hal yang tidak bisa Anda lakukan dengan menggunakan fungsi JavaScript yang ditentukan pengguna di Stream Analytics:

  • Panggil endpoint REST eksternal, misalnya, melakukan pencarian IP terbalik atau mengambil data referensi dari sumber eksternal
  • Lakukan serialisasi atau deserialisasi format event kustom pada input atau output
  • Membuat agregat kustom

Meskipun fungsi seperti Date.GetDate() atau Math.random() tidak diblokir dalam definisi fungsi, hindari menggunakannya. Fungsi-fungsi ini tidak mengembalikan hasil yang sama setiap kali Anda memanggilnya, dan layanan Azure Stream Analytics tidak menyimpan jurnal invokasi fungsi dan hasil yang dikembalikan. Jika sebuah fungsi mengembalikan hasil berbeda pada event yang sama, pengulangan tidak dijamin saat Anda atau layanan Stream Analytics memulai ulang pekerjaan tersebut.

Definisikan fungsi JavaScript yang ditentukan pengguna di portal Azure

Untuk pekerjaan Stream Analytics yang berjalan di cloud, tambahkan fungsi JavaScript yang ditentukan pengguna dari halaman Functions di bawah Job Topology, di mana menu +Add menyertakan opsi JavaScript UDF .

Catatan

Pengalaman ini berlaku untuk pekerjaan Stream Analytics yang dikonfigurasi untuk berjalan di cloud. Jika pekerjaan Azure Stream Analytics Anda dikonfigurasi untuk berjalan di Azure IoT Edge, gunakan Visual Studio dan tulis fungsi yang ditentukan pengguna menggunakan C#.

Tangkapan layar halaman Fungsi portal Azure yang menampilkan menu Tambah dengan opsi JavaScript UDF.

Definisi fungsi terdiri dari properti-properti berikut:

Properti Deskripsi
Alias fungsi Nama yang digunakan untuk memanggil fungsi dalam kueri Anda.
Jenis output Jenis yang dikembalikan fungsi JavaScript yang didefinisikan pengguna ke kueri Stream Analytics Anda.
Definisi fungsi Implementasi fungsi JavaScript Anda yang berjalan setiap kali UDF dipanggil dari kueri Anda.

Uji dan pemecahan masalah logika JavaScript UDF

Karena portal Stream Analytics tidak mendukung debugging dan pengujian logika fungsi yang ditentukan pengguna ini, Anda dapat menguji dan men-debug logika UDF JavaScript Anda di browser mana pun. Ketika fungsi berfungsi sesuai harapan, fungsi tersebut siap ditambahkan ke job Stream Analytics dan dipanggil langsung dari kueri Anda. Anda juga dapat menguji logika kueri Anda dengan JavaScript UDF menggunakan alat Stream Analytics untuk Visual Studio.

Stream Analytics memperlakukan kesalahan runtime JavaScript sebagai fatal dan menampilkannya melalui log Aktivitas. Log tersedia di portal Azure dari halaman log Aktivitas pekerjaan Anda.

Memanggil fungsi yang ditentukan pengguna JavaScript dalam kueri

Untuk memanggil fungsi JavaScript Anda dalam kueri, gunakan alias fungsi yang diawali udf. Contoh berikut menunjukkan UDF JavaScript yang mengubah nilai heksadesimal menjadi bilangan bulat dalam kueri Stream Analytics.

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

Objek JavaScript yang didukung

Fungsi yang didefinisikan pengguna JavaScript Azure Stream Analytics mendukung objek JavaScript standar bawaan. Objek-objek ini memberikan fungsi Anda akses ke operasi string umum, matematika, array, dan tanggal tanpa konfigurasi tambahan. Untuk daftar lengkap objek yang tersedia, lihat Objek Global. Karena bahasa kueri Stream Analytics dan JavaScript tidak memiliki sistem tipe yang sama, Stream Analytics mengonversi nilai saat berpindah antara keduanya.

Konversi tipe pada Stream Analytics dan JavaScript

Bahasa kueri Stream Analytics dan JavaScript mendukung berbagai tipe. Tabel ini mencantumkan pemetaan konversi di antara keduanya:

Analisis Aliran JavaScript
bigint Angka (JavaScript hanya dapat mewakili bilangan bulat hingga tepatnya 2^53)
DateTime Tanggal (JavaScript hanya mendukung milidetik)
dua kali lipat Nomor
nvarchar(MAX) String
Rekaman Objek
Array Array
NULL Null

Berikut adalah konversi JavaScript-ke-Azure Stream Analytics:

JavaScript Analisis Aliran
Nomor Bigint (jika angkanya bulat dan berada di antara long.MinValue dan long.MaxValue; jika tidak, nilainya adalah double)
Tanggal DateTime
String nvarchar(MAX)
Objek Rekaman
Array Array
Null, Tidak Terdefinisi NULL
Jenis lain (misalnya, fungsi atau kesalahan) Tidak didukung (mengakibatkan kesalahan runtime)

JavaScript peka terhadap perbedaan huruf besar dan huruf kecil, dan penggunaan huruf besar dan huruf kecil pada field objek dalam kode JavaScript harus sesuai dengan field dalam data yang masuk. Pekerjaan dengan tingkat kompatibilitas 1.0 mengubah bidang dari pernyataan SQL SELECT menjadi huruf kecil. Di bawah level kompatibilitas 1.1 ke atas, field dari pernyataan SELECT memiliki casing yang sama seperti yang ditentukan dalam query SQL.

Pola fungsi umum

Pola-pola berikut menunjukkan cara umum menggunakan fungsi yang didefinisikan pengguna JavaScript untuk mengubah data dalam kueri Stream Analytics Anda. Setiap pola mencakup definisi fungsi dan contoh kueri yang memanggilnya.

Tulis JSON bertingkat ke keluaran

Jika Anda memiliki langkah pemrosesan tindak lanjut yang menggunakan output pekerjaan Azure Stream Analytics sebagai input, dan memerlukan format JSON, Anda dapat menulis untai (karakter) JSON ke output. Definisi fungsi berikut memanggil fungsi JSON.stringify() untuk mengemas semua pasangan nama/nilai dari input lalu menuliskannya sebagai satu nilai string di output.

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

Kueri Stream Analytics memanggil fungsi seperti yang ditunjukkan pada contoh berikut.

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

Transmisikan untai (karakter) ke objek JSON untuk diproses

Jika Anda memiliki field string yang bernama JSON dan ingin mengubahnya menjadi objek JSON untuk diproses dalam UDF JavaScript, Anda dapat menggunakan fungsi JSON.parse() untuk membuat objek JSON yang kemudian dapat Anda gunakan. Definisi fungsi berikut mem-paris string dan mengembalikan properti dari objek yang dihasilkan.

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

Kueri Stream Analytics memanggil fungsi seperti yang ditunjukkan pada contoh berikut.

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

Gunakan coba/tangkap untuk penanganan kesalahan

Blok try/catch dapat membantu Anda mengidentifikasi masalah dengan data input yang salah yang Anda masukkan ke UDF JavaScript. Definisi fungsi berikut menggunakan blok try/catch untuk menangani kesalahan parsing.

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

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

Dalam kueri contoh berikut, Anda mengirimkan seluruh catatan sebagai parameter pertama agar fungsi dapat mengembalikannya jika terjadi kesalahan.

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

toLocaleString()

Metode toLocaleString dalam JavaScript mengembalikan string sensitif bahasa yang mewakili data tanggal-waktu dari mana Anda memanggil metode tersebut. Meskipun Azure Stream Analytics hanya menerima tanggal UTC sebagai timestamp sistem, Anda dapat menggunakan metode ini untuk mengonversi timestamp sistem ke lokal dan zona waktu lain. Metode ini mengikuti perilaku implementasi yang sama seperti yang tersedia di Internet Explorer. Definisi fungsi berikut mengonversi datetime input ke local de-DE .

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

Dalam kueri contoh berikut, datetime diberikan sebagai nilai input.

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

Hasil kueri ini adalah tanggal dan waktu masukan dalam format de-DE sesuai opsi yang diberikan.

Samstag, 28. December 2019

Pengelogan pengguna

Pencatatan adalah mekanisme yang digunakan Azure Stream Analytics untuk menangkap informasi khusus dari fungsi yang didefinisikan pengguna JavaScript saat pekerjaan berjalan. Karena pekerjaan yang berjalan biasanya tidak transparan, data log memberi Anda visibilitas terhadap perilaku dan kebenaran kode kustom Anda secara real time. Setiap pesan log membawa tingkat peristiwa yang menunjukkan seberapa signifikan pesan tersebut dan apakah pekerjaan dapat terus berjalan.

Pesan informasi berasal dari metode console.info(), seperti console.info('my info message');. Level ini merekam informasi umum selama eksekusi dan tidak mengganggu komputasi. Pesan peringatan berasal dari metode console.warn(), seperti console.warn('my warning message');. Level ini merekam data yang mungkin tidak terduga tetapi masih dapat diterima untuk perhitungan, sehingga pekerjaan tetap berjalan. Pesan kesalahan berasal dari metode console.error() dan console.log(), seperti console.error('my error message');. Metode ini hanya berlaku untuk kasus di mana kode tidak dapat dilanjutkan, sehingga mereka melemparkan pengecualian dengan informasi kesalahan yang disediakan dan menghentikan pekerjaan.

Anda dapat mengakses pesan log melalui log diagnostik.

atob() dan btoa()

Stream Analytics mendukung dua metode untuk konversi Base64, yang merupakan cara umum untuk mengkodekan data biner sebagai teks. Metode btoa() mengkodekan string ASCII ke dalam Base64, dan metode atob() mendekode string data yang dikodekan Base64 kembali ke string ASCII. Dalam contoh berikut, mengkodekan btoa() string ASCII, lalu atob() mendekode hasilnya kembali ke string asli.

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

Konten terkait

  • Last updated on