دوال JavaScript المعرفة من قبل المستخدم في Azure Stream Analytics

يدعم Azure Stream Analytics الدوال المعرفة من قبل المستخدم والمكتوبة في JavaScript. مع مجموعة غنية من أساليب السلسلة وRegExp والرياضيات والصفيف والتاريخ التي توفر JavaScript، وتحويلات البيانات المعقدة باستخدام دوال Stream Analytics تصبح أسهل في الإنشاء.

نظرة عامة

دوال JavaScript المعرفة من قبل المستخدم تدعم دوال عديمة الحالة وحسابية فقط ورقمية لا تتطلب اتصالاً خارجيًا. لا يمكن أن تكون قيمة إرجاع إحدى الدوال إلا قيمة رقمية (مفردة). بعد إضافة دالة JavaScript المعرفة من قبل المستخدم إلى وظيفة، يمكنك استخدام الدالة في أي مكان في الاستعلام كدالة رقمية مدمجة.

فيما يلي بعض السيناريوهات التي قد تستفيد فيها من دوال JavaScript المعرفة من قبل المستخدم:

• تحليل السلاسل التي لها دوال تعبير عادية، على سبيل المثال، Regexp_Replace() وRegexp_Extract()
• ترميز وفك ترميز البيانات، على سبيل المثال، تحويل ثنائي إلى سداسي
• القيام بحسابات الرياضيات باستخدام دوال JavaScript بالرياضيات
• القيام بعمليات الصفيف، مثل الفرز والانضمام والبحث والتعبئة

فيما يلي بعض الأشياء التي لا يمكنك القيام بها باستخدام دالة JavaScript معرفة من قبل مستخدم في Stream Analytics:

• استدعاء نقاط النهاية REST الخارجية، على سبيل المثال، القيام بالبحث العكسي عن عنوان IP أو سحب البيانات المرجعية من مصدر خارجي
• تنفيذ تسلسل تنسيق الحدث المخصص أو إلغاء تسلسله على المدخلات/ المخرجات
• إنشاء تجميعات مخصصة

على الرغم من أن الدوال مثل Date.GetDate() أو Math.random() غير محظورة في تعريف الدوال، يجب تجنب استخدامها. هذه الدوال لا ترجع نفس النتيجة في كل مرة تتصل بها، وخدمة Azure Stream Analytics لا تحتفظ بدفتر يومية استدعاءات الدوال والنتائج التي تم إرجاعها. إذا كانت إحدى الدوال ترجع نتيجة مختلفة في نفس الأحداث، فلن يتم ضمان التكرار عند إعادة تشغيل دالة من قبلك أو من قبل خدمة Stream Analytics.

إضافة دالة معرفة من قبل المستخدم JavaScript إلى وظيفتك

ملاحظة

تعمل هذه الخطوات على وظائف Stream Analytics التي تم تكوينها لتعمل في السحابة. إذا تم تكوين مهمة Stream Analytics لتعمل على Azure IoT Edge، فاستخدم Visual Studio بدلاً من ذلك واكتب الدالة المعرفة من قبل المستخدم باستخدام C#‎.

لإنشاء دالة JavaScript معرفة من قبل المستخدم في وظيفة Stream Analytics، حدد دوال ضمن طوبولوجيا الوظيفة. ثم، حدد JavaScript UDF من القائمة المنسدلة +إضافة.

بعد ذلك، لا بد من توفير الخصائص التالية وتحديد حفظ.

الخاصية	الوصف
الاسم المستعار للدالة	أدخل اسمًا لاستدعاء الدالة في الاستعلام.
نوع الإخراج	النوع الذي سيتم إرجاعه بواسطة دالة JavaScript المعرفة من قبل مستخدم إلى استعلام Stream Analytics.
تعريف الدالة	تنفيذ دالة JavaScript التي سيتم تنفيذها كل مرة يتم فيها استدعاء UDF الخاص بك من الاستعلام الخاص بك.

اختبار واستكشاف أخطاء JavaScript UDFs

يمكنك اختبار وتصحيح منطق JavaScript UDF في أي متصفح. تصحيح واختبار منطق هذه الدوال المعرفة من قبل المستخدم غير مدعوم حاليًا في مدخل Stream Analytics. بمجرد أن تعمل الدالة كما هو متوقع، يمكنك إضافتها إلى دالة Stream Analytics كما ذكر أعلاه، ثم استدعاؤها مباشرة من الاستعلام الخاص بك. يمكنك اختبار منطق الاستعلام الخاص بك باستخدام JavaScript UDF باستخدام أدوات Stream Analytics لـ Visual Studio.

تعتبر أخطاء وقت تشغيل JavaScript فادحة، ويتم عرضها من خلال سجل النشاط. لاسترداد السجل، في مدخل Azure، انتقل إلى وظيفتك وحدد سجل النشاط.

استدعاء دالة JavaScript معرفة من قبل المستخدم في استعلام

يمكنك بسهولة استدعاء دالة JavaScript في استعلامك باستخدام الاسم المستعار للدالة المثبتة مسبقًا باستخدام udf. وفيما يلي مثال على JavaScript UDF الذي يحول القيم الست عشرية إلى عدد صحيح يتم استدعاؤه في استعلام Stream Analytics.

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

كائنات JavaScript المدعومة

تدعم دوال Azure Stream Analytics JavaScript المعرفة من قبل المستخدم كائنات JavaScript القياسية المدمجة. للحصول على قائمة بهذه الكائنات، راجع الكائنات العمومية.

تحويل نوع Stream Analytics وJavaScript

هناك اختلافات في الأنواع التي تدعمها لغة استعلام Stream Analytics وJavaScript. يسرد هذا الجدول تعيينات التحويل بين الاثنين:

Stream Analytics	JavaScript
Bigint	رقم (يمكن أن تمثل JavaScript أعدادًا صحيحة فقط تصل إلى 2^53 بالضبط)
التاريخ والوقت	التاريخ (JavaScript يدعم ميلي ثانية فقط)
مزدوج	الهاتف
nvarchar(MAX)	سلسلة
سجل	عنصر
صفيف	صفيف
القيمة الخالية	خالٍ

فيما يلي تحويلات JavaScript إلى Stream Analytics:

JavaScript	Stream Analytics
الهاتف	Bigint (إذا كان العدد مقربًا وبين long.MinValue وlong.MaxValue؛ بخلاف ذلك، يكون مضاعفًا)
التاريخ	التاريخ والوقت
سلسلة	nvarchar(MAX)
عنصر	سجل
صفيف	صفيف
خالٍ، غير معرف	القيمة الخالية
أي نوع آخر (على سبيل المثال، دالة أو خطأ)	غير معتمد (النتائج في وقت التشغيل خاطئة)

لغة JavaScript حساسة لحالة الأحرف ويجب أن تتطابق حالة حقول الكائنات في رمز JavaScript مع حالة الحقول في البيانات الواردة. ستقوم الوظائف بمستوى التوافق 1.0 بتحويل الحقول من عبارة SQL SELECT لتكون صغيرة. تحت مستوى التوافق 1.1 وأعلى، الحقول من عبارة SELECT يكون لها نفس الحالة المحددة في استعلام SQL.

أنماط دوال JavaScript معرفة من قبل المستخدم أخرى

كتابة JSON المتداخلة للإخراج

إذا كانت لديك خطوة معالجة متابعة تستخدم إخراج وظيفة Stream Analytics كمدخل، وتتطلب تنسيق JSON، يمكنك كتابة سلسلة JSON لإخراجها. المثال التالي يستدعي الدالة JSON.stringify() لحزم كافة أزواج الاسم/ القيمة من الإدخال، ثم كتابتها كقيمة سلسلة واحدة في الإخراج.

تعريف دوال JavaScript المعرفة من قبل المستخدم:

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

نموذج استعلام:

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

تحويل سلسلة إلى كائن JSON للمعالجة

إذا كان لديك حقل سلسلة JSON وتريد تحويله إلى كائن JSON للمعالجة في JavaScript UDF، يمكنك استخدام الدالة JSON.parse() لإنشاء كائن JSON يمكن استخدامه بعد ذلك.

تعريف دوال JavaScript المعرفة من قبل المستخدم:

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

نموذج استعلام:

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

استخدام try/catch لمعالجة الخطأ

يمكن أن تساعدك كتل Try/catch في تحديد المشكلات المتعلقة ببيانات الإدخال المشوهة التي يتم تمريرها إلى وحدة دفاع JavaScript UDF.

تعريف دوال JavaScript المعرفة من قبل المستخدم:

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

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

نموذج استعلام: قم بتمرير السجل بأكمله كمعلمة أولى بحيث يمكن إرجاعه إذا كان هناك خطأ.

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

toLocaleString()

يمكن استخدام أسلوب toLocaleString في JavaScript لإرجاع سلسلة حساسة للغة تمثل بيانات وقت التاريخ، والتي يتم منها استدعاء هذا الأسلوب. على الرغم من أن Azure Stream Analtyics لا يقبل سوى تاريخ ووقت UTC كطابع زمني للنظام، يمكن استخدام هذه الطريقة لتحويل الطابع الزمني للنظام إلى موقع آخر ومنطقة زمنية أخرى. يتبع هذا الأسلوب سلوك التنفيذ نفسه الذي يتوفر في Internet Explorer.

تعريف دوال JavaScript المعرفة من قبل المستخدم:

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

نموذج استعلام: قم بتمرير تاريخ ووقت كقيمة إدخال

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

سيكون إخراج هذا الاستعلام تاريخ إدخال ووقته في de-DE باستخدام الخيارات المتوفرة.

Samstag, 28. Dezember 2019

تسجيل دخول المستخدم

تسمح آلية التسجيل للمستخدمين بالتقاط معلومات مخصصة أثناء تشغيل الوظيفة. يمكن استخدام بيانات السجل لتصحيح أخطاء التعليمات البرمجية المخصصة أو تقييمها في الوقت الفعلي. تتوفر هذه الآلية من خلال ثلاث طرق مختلفة.

Console.Info()

يتم استخدام أسلوب Console.Info لتسجيل المعلومات العامة أثناء تنفيذ التعليمات البرمجية. سيقوم هذا الأسلوب بتسجيل البيانات دون مقاطعة الحساب. سيتم وضع علامة على الرسالة التي تم تسجيلها على أنها معلوماتية على مستوى الحدث.

console.info('my info message');

Console.Warn()

يتم استخدام أسلوب Console.Warn لتسجيل البيانات التي قد لا تكون صحيحة أو متوقعة ولكنها لا تزال مقبولة للحساب. لن يقطع هذا الأسلوب الحساب وسيستأنف تشغيله بعد إرجاع الأسلوب. سيتم وضع علامة على الرسالة التي تم تسجيلها على أنها تحذير على مستوى الحدث.

console.warn('my warning message');

Console.Error() و Console.Log()

يتم استخدام أسلوب Console.Error فقط لتسجيل حالات الخطأ حيث لا يمكن متابعة تشغيل التعليمات البرمجية. سيطرح هذا الأسلوب استثناء مع معلومات الخطأ المقدمة حيث ستتوقف معلمة الإدخال والمهمة عن التشغيل. سيتم وضع علامة على رسالة الخطأ التي تم تسجيلها كخطأ على مستوى الحدث.

console.error('my error message');

يمكنك الوصول إلى رسائل السجل من خلال سجلات التشخيص.

atob() وbtoa()

يمكن استخدام الأسلوب btoa() لترميز سلسلة ASCII في Base64. يتم ذلك عادة لنقل البيانات بتنسيق ثنائي. يمكن استخدام أسلوب atob() لفك ترميز سلسلة من البيانات المشفرة في Base64 إلى تنسيق سلسلة ASCII.

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

الخطوات التالية

• التعلم الآلي UDF
• C# UDF