Share via

تطوير دالات.NET Standard المعرفة من قبل المستخدم لوظائف Azure Stream Analytics (إصدار أولي)

  • مقالة

هام

سيتم إيقاف وظائف .Net Standard المعرفة من قبل المستخدم ل Azure Stream Analytics في 30 سبتمبر 2024. بعد ذلك التاريخ، لن يكون من الممكن استخدام الميزة. يرجى الانتقال إلى وظائف JavaScript المعرفة من قبل المستخدم ل Azure Stream Analytics.

يقدم Azure Stream Analytics لغة استعلام تشبه لغة الاستعلامات المركبة لإجراء التحويلات والحسابات عبر تدفقات بيانات الحدث. هناك العديد من الدالات المُضمنة، ولكن تتطلب بعض السيناريوهات المعقدة مرونة إضافية. باستخدام الدالات المعرفة من قبل المستخدم .NET Standard (UDF)، يُمكنك استدعاء الدالات الخاصة بك المكتوبة بأي لغة .NET قياسية (C#، F#، وما إلى ذلك) لتوسيع لغة استعلام Stream Analytics. تسمح لك الدالات المعرفة من قبل المستخدم بإجراء حسابات رياضية معقدة، واستيراد نماذج التعلم الآلي من Microsoft Azure المخصصة باستخدام ML.NET، واستخدام منطق الإسناد المخصص للبيانات المفقودة. ميزة UDF لوظائف Stream Analytics قيد المعاينة حالياً، ولا يجب استخدامها في أعباء العمل الإنتاجية.

المناطق

يتم تمكين ميزة الدالة المعرفة من قبل المستخدم .NET للوظائف السحابية التي تعمل على نظم مجموعات Stream Analytics. يُمكن للوظائف التي تعمل على وحدة حفظ المخزون القياسي متعدد المستأجرين الاستفادة من هذه الميزة في المناطق العامة التالية:

  • غرب وسط الولايات المتحدة
  • أوروبا الشمالية
  • شرق الولايات المتحدة
  • غرب الولايات المتحدة
  • East US 2
  • أوروبا الغربية

في حال كنت مهتمًا باستخدام هذه الميزة في أي منطقة أخرى، يمكنك طلب الوصول.

مسار الحزمة

يحتوي تنسيق أي حزمة دالات معرفة من قبل المستخدم على المسار /UserCustomCode/CLR/*. تُنسخ مكتبات الارتباطات الديناميكية والموارد ضمن المجلد /UserCustomCode/CLR/*، مما يساعد على عزل مكتبات الارتباطات الديناميكية للمستخدم عن النظام وعناوين DLL ل Azure Stream Analytics. يُستخدم مسار الحزمة هذا لجميع الدالات بغض النظر عن الطريقة المستخدمة لاستخدامها.

الأنواع المعتمدة والتعيينات

حتى يتم استخدام قيم Azure Stream Analytics في C#، يجب تنظيمها من بيئة إلى أخرى. يحدث تنظيم وإرسال لجميع معلمات الإدخال للدالات المعرفة من قبل المستخدم. يحتوي كل نوع من أنواع Azure Stream Analytics على نوع مطابق في C# الموضحِ في الجدول أدناه:

نوع Azure Stream Analytics نوع C#‎
عدد صحيح كبير طويل
عائم مزدوج
nvarchar(max) سلسلة
datetime DateTime
سجل القاموس<سلسلة، عنصر>
صفيف Object[]

ينطبق الشيء نفسه عندما تحتاج البيانات إلى تنظيم من C# إلى Azure Stream Analytics، والذي يحدث على قيمة إخراج دالة معرفة من قبل المستخدم. يُوضح الجدول أدناه الأنواع المعتمدة:

نوع C#‎ نوع Azure Stream Analytics
طويل عدد صحيح كبير
مزدوج عائم
سلسلة nvarchar(max)
DateTime dateTime
بنية سجل
كائن سجل
Object[] صفيف
القاموس<سلسلة، عنصر> سجل

تطوير دالة معرفة من قبل المستخدم في Visual Studio Code

تسهّل أدوات Visual Studio Code ل Azure Stream Analytics من كتابة الدالات المعرفة من قبل المستخدم واختبار مهامك محليًا (حتى دون اتصال) ونشر وظيفة Stream Analytics إلى Azure.

هناك طريقتان لتنفيذ دالات معرفة من قبل المستخدم قياسية .NET في أدوات Visual Studio Code.

  • دالة معرفة من قبل المستخدم من مكتبة ارتباطات ديناميكية محلية
  • دالة معرفة من قبل المستخدم من مشروع محلي

المشروع المحلي

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

للإشارة إلى مشروعٍ محلي:

  1. إنشاء مكتبة فئات قياسية جديدة .NET على الجهاز المحلي الخاص بك.
  2. اكتب التعليماتِ البرمجية في الصف الخاص بك. ينبغي تعريف جميع الفئات على أنها عامة ويجب تعريف جميع الكائنات تحت صفة عام ثابت.
  3. إضافة ملف تكوين وظيفة CSharp جديد في مشروع Azure Stream Analytics والإشارة إلى مشروعِ مكتبة فئة CSharp.
  4. تكوين مسار التجميع في ملف تكوينِ الوظيفة، JobConfig.json، قسم CustomCodeStorage. هذه الخطوة غير مطلوبة للاختبار المحلي.

مكتبات ارتباطات ديناميكية محلية

يُمكنك أيضا الرجوع إلى مكتبات الارتباطات الديناميكية المحلية التي تتضمن الدالات المعرفة من قبل المستخدم.

مثال

في هذا المثال، CSharpUDFProject هو مشروع مكتبة فئة C#‎ وASAUDFDemo هو مشروع Azure Stream Analytics، والذي سيُشير إلى CSharpUDFProject.

Azure Stream Analytics project in Visual Studio Code

تحتوي الدالة المعرفة من قبل المستخدم التالي على دالة تضرب عددا صحيحا في حد ذاته لإنتاج مربع العدد الصحيح. يجب تعريف الفئات على أنها عامة ويجب تعريف العناصر تحت صفة عام ثابت.

using System;

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

تُوضح لك الخطوات التالية كيفية إضافة دالة معرفة من قبل المستخدم C# إلى مشروع Stream Analytics.

  1. انقر بزر الماوس الأيمن فوق مجلد Functions واختر Add Item.

    Add new function in Azure Stream Analytics project

  2. أضِف دالة C#‎ SquareFunction إلى مشروع Azure Stream Analytics الخاص بك.

    Select CSharp function from Stream Analytics project in VS Code

    Enter CSharp function name in VS Code

  3. في تكوين الدالة C#، حدد Choose library project path لاختيار مشروع C# من القائمة المنسدلة وحدد Build project لإنشاء مشروعك. ثم اختر Select class و Select method لتحديد الفئة ذات الصلة واسم الأسلوبِ من القائمة المنسدلة. للإشارة إلى الأساليب والأنواع والدالات في استعلام Stream Analytics، يجب تعريف الفئاتِ على أنها عامة ويجب تعريف الكائنات على أنها عامة ثابتة.

    Stream Analytics C sharp function configuration VS Code

    في حال كنت تريد استخدام الدالة المعرفة من قبل المستخدم C# من مكتبة ارتباطات ديناميكية، فحدد Choose library dll path لاختيار مكتبة الارتباطات الديناميكية. ثم اختر Select class و Select method لتحديد الفئة ذات الصلة واسم الأسلوبِ من القائمة المنسدلة.

    Stream Analytics C sharp function configuration

  4. قم باستدعاء دالة معرفة من قبل المستخدم في استعلام Azure Stream Analytics.

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

  5. قبل إرسال المهمة إلى Azure، قم بتكوين مسار الحزمة في ملف تكوين الوظيفة، JobConfig.json، وقسم CustomCodeStorage. استخدم Select from your subscription في CodeLens لاختيار اشتراكك واختر حساب التخزين واسم الحاوية من القائمة المنسدلة. اترك Path افتراضيًا. هذه الخطوة غير مطلوبة للاختبارِ المحلي.

    Choose library path

تطوير دالة معرّفة من قبل المستخدم في Visual Studio

ثمة ثلاث طرق لتنفيذ الدالات المعرفة من قبل المستخدم في أدوات Visual Studio.

  • ملفات CodeBehind في مشروعِ ASA
  • دالة معرفة من قبل المستخدم من مشروع محلي
  • حزمة موجودة من حساب تخزينِ Azure

CodeBehind

بإمكانك كتابة الدالات المعرفة من قبل المستخدم في Script.asql CodeBehind. ستقوم أدوات Visual Studio تلقائيًا بتحويل ملف CodeBehind برمجيا إلى ملف تجميع. تُحزم التجميعات كملف مضغوط وتحميلها إلى حساب التخزين الخاص بك عند إرسال وظيفتك إلى Azure. بإمكانك تعلم كيفية كتابة الدالة المعرفة من قبل المستخدم C# باستخدام CodeBehind باتباع البرنامج التعليمي C#دالة معرفة من قبل المستخدم لمهام Stream Analytics Edge.

المشروع المحلي

للإشارة إلى مشروعٍ محلي في Visual Studio:

  1. إنشاء مكتبة فئات قياسية .NET جديدة في حلك
  2. اكتب التعليماتِ البرمجية في الصف الخاص بك. ينبغي تعريف جميع الفئات على أنها عامة ويجب تعريف جميع الكائنات تحت صفة عام ثابت.
  3. أنشئ مشروعك. ستحزم الأدوات جميع البيانات الاصطناعية في مجلد الحاوية إلى ملف مضغوط وتحميل الملف المضغوط إلى حساب التخزين. فيما يتعلق بالمراجع الخارجية، استخدم مرجع التجميع بدلا من حزمة NuGet.
  4. الرجوع إلى الفئةِ الجديدة في مشروع Azure Stream Analytics.
  5. أضف دالة جديدة في مشروع Azure Stream Analytics الخاص بك.
  6. كوّن مسار التجميع في ملف تكوين الوظيفة، JobConfig.json. عيّن مسار التجميع إلى مرجع المشروع المحلي أو CodeBehind.
  7. إعادة إنشاء كل من مشروع الدالةِ ومشروع Azure Stream Analytics.

مثال

في هذا المثال، UDFTest هو مشروع مكتبة فئة C# و ASAUDFDemo هو مشروع Azure Stream Analytics، والذي سيشير إلى UDFTest.

Azure Stream Analytics IoT Edge project in Visual Studio

  1. أنشئ مشروع C# الخاص بك، والذي سيمكّنك من إضافة مرجع إلى C# UDF الخاص بك من استعلام Azure Stream Analytics.

    Build an Azure Stream Analytics IoT Edge project in Visual Studio

  2. أضِف المرجع إلى مشروع C# في مشروع ASA. انقر بزر الماوس الأيمن فوق عقدة المراجع واختر Add Reference.

    Add a reference to a C# project in Visual Studio

  3. اختر اسم مشروعِ C# من القائمة.

    Choose your C# project name from the reference list

  4. يجب أن ترى UDFTest مدرجا ضمن References في Solution Explorer.

    View the user defined function reference in solution explorer

  5. انقر بزر الماوس الأيمن فوق مجلدِ Functions واختر New Item.

    Add new item to Functions in Azure Stream Analytics Edge solution

  6. أضِف دالة C#‎ SquareFunction.json إلى مشروع Azure Stream Analytics الخاص بك.

    Select CSharp function from Stream Analytics Edge items in Visual Studio

  7. انقر نقرا مزدوجا فوق الدالة في Solution Explorer لفتح مربع حوار التكوين.

    C sharp function configuration in Visual Studio

  8. في تكوين الدالة C#، اختر Load from ASA Project Reference وأسماء التجميع والفئة والأسلوب ذات الصلة من القائمة المنسدلة. للإشارة إلى الأساليب والأنواع والدالات في استعلام Stream Analytics، يجب تعريف الفئاتِ على أنها عامة ويجب تعريف الكائنات على أنها عامة ثابتة.

    Stream Analytics C sharp function configuration Visual Studio

حزم موجودة

يُمكنك تأليف .دالات معرفة من قبل المستخدم NET Standard في أي بيئة التطوير المتكامل من اختيارك واستدعائها من استعلام Azure Stream Analytics. أولا قم بتجميع التعليمات البرمجية الخاصة بك وحزم جميع مكتبات ارتباطات ديناميكية. يحتوي تنسيق الحزمةِ على المسار /UserCustomCode/CLR/*. ثم قم بالتحميل UserCustomCode.zip إلى جذر الحاوية في حساب تخزينِ Azure الخاص بك.

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

لتكوين مسار التجميع في ملف تكوين الوظيفة، JobConfig.json:

وسع قسم تكوين التعليمات البرمجية المعرفة من قِبَل المستخدم ثم املأ التكوين بالقيم المقترحة التالية:

الإعداد القيم المقترحة
مورد إعدادات التخزين العام اختيار مصدر البيانات من حساب جارٍ
اشتراك إعدادات التخزين العام < اشتراكك >
حساب تخزين إعدادات التخزين العام < حساب التخزين الخاص بك >
مورد إعدادات تخزين الرمز المخصص اختيار مصدر البيانات من حساب جارٍ
حساب تخزين إعدادات الرمز المخصص < حساب التخزين الخاص بك >
حاوية إعدادات تخزين الرمز المخصص < حاوية التخزين الخاصة بك >
مصدر تجميع التعليمات البرمجية المُخصصة حِزم التجميع الموجودة من السحابة
مصدر تجميع التعليمات البرمجية المُخصصة UserCustomCode.zip

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

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

تتيح لك الفئة StreamingContext نشر معلومات التشخيص باستخدام الدالة StreamingDiagnostics.WriteError. تظهر التعليمات البرمجية أدناه الواجهة التي يعرضها Azure Stream Analytics.

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

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

StreamingContext يتم تمرير كمعلمة إدخال إلى أسلوب دالة معرفة من قبل المستخدم ويمكن استخدامه داخل دالة معرفة من قبل المستخدم لنشر معلومات السجل المخصصة. في المثال أدناه، MyUdfMethod يعرف إدخال البيانات، الذي يوفره الاستعلام، وإدخال سياق مثل StreamingContext، الذي يوفره محرك وقت التشغيل.

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

لا تحتاج القيمة StreamingContext إلى تمريرها بواسطة استعلام SQL. يُوفر Azure Stream Analytics كائن سياق تلقائيًا إذا كانت معلمة الإدخال موجودة. لا يتغير استخدام MyUdfMethod، كما هو موضح في الاستعلام التالي:

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

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

القيود

تحتوي هذه الميزة حالياً على القيود التالية:

  • لا يمكن تأليف دالة معرفة من قبل المستخدم.NET Standard إلا في Visual Studio Code أو Visual Studio ونشرها في Azure. يمكن عرض إصدارات للقراءة فقط من دالات معرفة من قبل المستخدم .NET Standard ضمن Functions في مدخل Microsoft Azure. تأليف الدالات .NET Standard غير مُعتمد في مدخل Microsoft Azure.

  • يعرض محرر استعلام مدخل Microsoft Azure خطأ عند استخدام دالة معرفة من قبل المستخدم .NET Standard في المدخل.

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

  • نظرًا لأن التعليمات البرمجية المخصصة تشارك السياق مع محرك Azure Stream Analytics، لا يمكن للتعليمات البرمجية المخصصة الرجوع إلى أي شيء يحتوي على مساحة اسم/dll_name متعارضة مع التعليمات البرمجية لـ Azure Stream Analytics. على سبيل المثال، لا يُمكنك الرجوع إلى Newtonsoft Json.

  • تُنسخ الملفات الداعمة المضمنة في المشروع إلى ملف الرمز البريدي المخصص للمستخدم الذي يتم استخدامه عند نشر المهمة على السحابة. تُنسخ جميع الملفات في المجلدات الفرعية مباشرة إلى جذر مجلد "التعليمات البرمجية المخصصة للمستخدم" في السحابة عند إلغاء ضغطها. يتم "تسطيح" الرمز البريدي عند فكِ ضغطه.

  • لا تدعم التعليمات البرمجية المُخصصة للمستخدم المجلدات الفارغة. لا تقم بإضافة مجلدات فارغة إلى الملفاتِ الداعمة في المشروع.

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