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

يدعم Azure Stream Analytics الدوال المعرفة من قبل المستخدم والمكتوبة في JavaScript. باستخدام مجموعة غنية من طرق String، RegExp، Math، Array، وDate التي توفرها JavaScript، يمكنك إنشاء تحويلات بيانات معقدة في وظائف تحليلات التدفق. دوال JavaScript المعرفة من قبل المستخدم تدعم دوال عديمة الحالة وحسابية فقط ورقمية لا تتطلب اتصالاً خارجيًا. لا يمكن أن تكون قيمة إرجاع إحدى الدوال إلا قيمة رقمية (مفردة). بعد إضافة دالة JavaScript المعرفة من قبل المستخدم إلى وظيفة، يمكنك استخدام الدالة في أي مكان في الاستعلام كدالة رقمية مدمجة.

تشرح هذه المقالة متى تستخدم وظائف JavaScript المعرفة من قبل المستخدم وكيفية تعريفها واستدعاؤها في وظائف تحليلات التدفق الخاصة بك.

متى تستخدم دالة جافاسكريبت المعرفة من قبل المستخدم

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

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

إليك بعض الأمور التي لا يمكنك القيام بها باستخدام وظيفة يحددها المستخدم في JavaScript في Stream Analytics:

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

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

تعريف دالة معرفة من قبل المستخدم بجافا سكريبت في بوابة Azure

بالنسبة لوظيفة تحليلات التدفق التي تعمل في السحابة، أضف دالة معرفة من قبل المستخدم بجافاسكريبت من صفحة الوظائف تحت طوبولوجيا الوظائف، حيث تتضمن قائمة +Add خيار UDF بجافا سكريبت .

إشعار

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

يتكون تعريف الدوال من الخصائص التالية:

الخاصية	‏‏الوصف
الاسم المستعار للدالة	الاسم الذي يستدعي الدالة في استعلامك.
نوع الإخراج	النوع الذي تعيده وظيفة جافاسكريبت المعرفة من قبل المستخدم إلى استعلام تحليلات التدفق الخاص بك.
تعريف الدالة	تنفيذ وظيفة جافاسكريبت التي تعمل في كل مرة يتم فيها استدعاء UDF من استعلامك.

اختبر واستكشاف أخطاء منطق UDF في JavaScript

نظرا لأن بوابة تحليلات التدفق لا تدعم تصحيح واختبار منطق هذه الوظائف المعرفة من قبل المستخدم، يمكنك اختبار وتصحيح منطق UDF الخاص بجافاسكريبت في أي متصفح. عندما تعمل الوظيفة كما هو متوقع، تكون جاهزة للإضافة إلى وظيفة تحليلات التدفق والاستدعاء مباشرة من استفسارك. يمكنك أيضا اختبار منطق الاستعلام باستخدام UDF بجافاسكريبت باستخدام أدوات Stream Analytics الخاصة ب Visual Studio.

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

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

لتفعيل وظيفة جافاسكريبت الخاصة بك في استفسارك، استخدم الدالة المستعارة التي تسبق لها كلمة udf. المثال التالي يظهر واجهة UDF بجافاسكريبت تحول القيم السداسية عشرية إلى عدد صحيح في استعلام تحليلات التدفق.

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

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

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

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

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

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

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

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

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

أنماط الوظائف المشتركة

الأنماط التالية تعرض طرقا شائعة لاستخدام وظائف جافاسكريبت المعرفة من قبل المستخدم لتحويل البيانات في استعلامات تحليلات التدفق الخاصة بك. كل نمط يتضمن تعريف دالة واستعلام عينة يستدعيه.

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

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

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 للمعالجة في UDF بجافاسكريبت، يمكنك استخدام دالة JSON.parse() لإنشاء كائن JSON يمكنك استخدامه بعد ذلك. تعريف الدالة التالي يحلل السلسلة ويعيد خاصية من الكائن الناتج.

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

يستدعي استعلام تحليلات التدفق الدالة كما هو موضح في المثال التالي.

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

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

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

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 في جافا سكريبت تعيد سلسلة نصية حساسة للغة تمثل بيانات التاريخ والوقت من المكان الذي تستدعي فيه الطريقة. على الرغم من أن Azure Stream Analytics يقبل فقط التاريخ والتوقيت ب UTC كطابع زمني للنظام، يمكنك استخدام هذه الطريقة لتحويل طابع النظام الزمني إلى موقع ومنطقة زمنية أخرى. تتبع هذه الطريقة نفس سلوك التنفيذ الموجود في Internet Explorer. تعريف الدالة التالي يحول تاريخ الإدخال إلى الموقع de-DE .

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. December 2019

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

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

تأتي الرسائل المعلوماتية من طريقة console.info() مثل console.info('my info message');. هذا المستوى يسجل المعلومات العامة أثناء التنفيذ ولا يقطع الحساب. تأتي رسائل التحذير من طريقة console.warn() مثل console.warn('my warning message');. يسجل هذا المستوى بيانات قد تكون غير متوقعة لكنها لا تزال مقبولة للحساب، لذا تستمر المهمة في العمل. تأتي رسائل الخطأ من طريقتي console.error() و console.log() مثل console.error('my error message');. تنطبق هذه الطرق فقط على الحالات التي لا يمكن فيها استمرار الكود، لذا يتم وضع استثناء مع معلومات الخطأ المقدمة وتوقف المهمة.

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

atob() وbtoa()

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

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

المحتوى ذو الصلة

• التعلم الآلي UDF
• الدوال المعرفة من قبل المستخدم في C#‎