إنشاء مسارات الأحداث وعوامل التصفية في Azure Digital Twins

ترشدك هذه المقالة خلال عملية إنشاء مسارات الأحداث باستخدام مدخل Microsoft Azure، والأوامر Azure CLI az dt route، وواجهات برمجة تطبيقات مستوى بيانات مسارات الأحداث، و.NET (C#) SDK.

توجيه إعلامات الأحداث من Azure Digital Twins إلى خدمات انتقال البيانات من الخادم أو موارد الحوسبة المتصلة هي عملية من خطوتين: إنشاء نقاط النهاية، ثم إنشاء مسارات الأحداث لإرسال البيانات إلى نقاط النهاية هذه. تتناول هذه المقالة الخطوة الثانية، إعداد المسارات للتحكم في الأحداث التي يتم تسليمها إلى نقاط نهاية Azure Digital Twin. لمتابعة هذه المقالة، يجب أن يكون لديك نقاط نهاية تم إنشاؤها بالفعل.

المتطلبات الأساسية

• ستحتاج إلى حساب Azure، والذي يمكن إعداده مجانا

• ستحتاج إلى مثيل Azure Digital Twins في اشتراك Azure. إذا لم يكن لديك مثيل بالفعل، يمكنك إنشاء مثيل باستخدام الخطوات الواردة في إعداد مثيل ومصادقة. استخدم القيم التالية من الإعداد بسهولة لاستخدامها لاحقا في هذه المقالة:

  • اسم مثيل
  • مجموعة الموارد

  يمكنك العثور على هذه التفاصيل في مدخل Microsoft Azure بعد إعداد المثيل الخاص بك.

  

• إنشاء نقطة نهاية باستخدام الإرشادات الموجودة في إنشاء نقاط النهاية. في هذه المقالة، ستقوم بإنشاء مسار لإرسال البيانات إلى نقطة النهاية هذه.

بعد ذلك، اتبع الإرشادات أدناه إذا كنت تنوي استخدام Azure CLI أثناء اتباع هذا الدليل.

إعداد البيئة الخاصة بك لـ Azure CLI

• استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.

  

• إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

  • إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.

  • عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.

  • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

إنشاء مسار الحدث

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

إشعار

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

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

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

يمكن أن يحتوي تعريف المسار على هذه العناصر:

• اسم المسار الذي تريد استخدامه
• اسم نقطة النهاية التي تريد استخدامها
• عامل تصفية يحدد الأحداث التي يتم إرسالها إلى نقطة النهاية
  • لتعطيل المسار بحيث لا يتم إرسال أي أحداث، استخدم قيمة عامل تصفية false
  • لتمكين مسار لا يحتوي على تصفية محددة، استخدم قيمة عامل تصفية true
  • للحصول على تفاصيل حول أي نوع آخر من عوامل التصفية ، راجع قسم أحداث التصفية أدناه

إذا لم يكن هناك اسم مسار، فلن يتم توجيه أي رسائل خارج Azure Digital Twins. إذا كان هناك اسم مسار وكان عامل التصفية هو true، يتم توجيه جميع الرسائل إلى نقطة النهاية. إذا كان هناك اسم مسار وتم إضافة عامل تصفية مختلف، فستتم تصفية الرسائل استنادا إلى عامل التصفية.

يمكن إنشاء مسارات الأحداث باستخدام مدخل Azure أو واجهات برمجة تطبيقات مستوى بيانات EventRoutes أو أوامر az dt route CLI. يستعرض باقي هذا القسم عملية الإنشاء.

بوابة

لإنشاء مسار حدث، انتقل إلى صفحة التفاصيل لمثيل Azure Digital Twins في مدخل Microsoft Azure (يمكنك العثور على المثيل عن طريق إدخال اسمه في شريط بحث المدخل).

من قائمة المثيل، حدد مسارات الأحداث. ثم من صفحة مسارات الأحداث التالية، حدد + إنشاء مسار حدث.

في صفحة Create an event route التي تفتح، اختر على الأقل:

• اسم لمسارك في حقل الاسم
• نقطة النهاية التي تريد استخدامها لإنشاء المسار

لتمكين المسار، يجب أيضا إضافة عامل تصفية مسار حدث على الأقل true. (سيؤدي ترك القيمة الافتراضية للمسار false إلى إنشاء المسار، ولكن لن يتم إرسال أي أحداث إليه.) للقيام بذلك، قم بتبديل مفتاح المحرر المتقدم لتمكينه، واكتب true في المربع تصفية .

عند الانتهاء، حدد الزر حفظ لإنشاء مسار الحدث.

المبادره القطريه

يمكن إدارة المسارات باستخدام أوامر توجيه az dt ل Azure Digital Twins CLI.

لمزيد من المعلومات حول استخدام CLI والأوامر المتوفرة، راجع مجموعة أوامر Azure Digital Twins CLI.

.NET SDK

يوضح هذا القسم كيفية إنشاء مسار حدث باستخدام .NET (C#) SDK.

CreateOrReplaceEventRouteAsync هو استدعاء SDK الذي يستخدم لإضافة مسار حدث. فيما يلي مثال على استخدامه:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

تلميح

تأتي جميع وظائف SDK في إصدارات متزامنة وغير متزامنة.

نموذج رمز SDK لمسار الحدث

يوضح أسلوب النموذج التالي كيفية إنشاء مسار حدث وإدراجه وحذفه باستخدام C# SDK:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

أحداث التصفية

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

بعد تمكين الحد الأدنى من trueعامل تصفية ، ستتلقى نقاط النهاية أنواعا مختلفة من الأحداث من Azure Digital Twins:

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

يمكنك تقييد أنواع الأحداث التي يتم إرسالها عن طريق تحديد عامل تصفية أكثر تحديدًا.

إشعار

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

بوابة

لإضافة عامل تصفية حدث أثناء إنشاء مسار حدث، استخدم قسم إضافة عامل تصفية مسار حدث في صفحة إنشاء مسار حدث.

يمكنك إما الاختيار من بين بعض خيارات التصفية الأساسية الشائعة، أو استخدام خيارات التصفية المتقدمة لكتابة عوامل التصفية المخصصة الخاصة بك.

استخدام عوامل التصفية الأساسية

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

سيؤدي القيام بذلك إلى ملء مربع نص عامل التصفية تلقائيا مع نص عامل التصفية الذي حددته:

استخدام عوامل التصفية المتقدمة

يمكنك أيضا استخدام خيار التصفية المتقدمة لكتابة عوامل التصفية المخصصة الخاصة بك.

لإنشاء مسار حدث باستخدام خيارات التصفية المتقدمة، بدِّل المفتاح الخاص بالمحرر المتقدم لتمكينه. يمكنك بعد ذلك كتابة عوامل تصفية الأحداث الخاصة بك في مربع عامل التصفية:

API

يمكنك استخدام واجهات برمجة تطبيقات مستوى بيانات مسارات الأحداث لكتابة عوامل تصفية مخصصة. لإضافة عامل تصفية، يمكنك استخدام طلب PUT إلى https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 مع النص الأساسي التالي:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

عوامل تصفية التوجيه المدعومة

فيما يلي عوامل تصفية المسار المدعومة.

اسم عامل التصفية	‏‏الوصف	تصفية مخطط النص	القيم المدعومة
صحيح/ خطأ	يسمح بإنشاء مسار بدون تصفية أو تعطيل مسار حتى لا يتم إرسال أي أحداث	<true/false>	true = تم تمكين المسار بدون تصفية false = تم تعطيل المسار
نوع	نوع الحدث المتدفق من خلال مثيل التوأم الرقمي الخاص بك	type = '<event-type>'	فيما يلي قيم نوع الحدث المحتملة: Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.Update Microsoft.DigitalTwins.Relationship.Create Microsoft.DigitalTwins.Relationship.Update Microsoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry
المصدر	اسم مثيل Azure Digital Twins	source = '<host-name>'	فيما يلي قيم اسم المضيف المحتملة: للحصول على الإعلامات: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net لبيانات تتبع الاستخدام: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
الموضوع	وصف الحدث في سياق مصدر الحدث أعلاه	subject = '<subject>'	فيما يلي قيم الموضوع المحتملة: للإعلامات: الموضوع هو <twin-ID> أو تنسيق URI للمواضيع، التي يتم تعريفها بشكل فريد بواسطة أجزاء أو معرفات متعددة: <twin-ID>/relationships/<relationship-ID> لبيانات تتبع الاستخدام: الموضوع هو مسار المكون (إذا تم إصدار بيانات تتبع الاستخدام من مكون مزدوج)، مثل comp1.comp2. إذا لم يتم إصدار بيانات تتبع الاستخدام من مكون، فسيكون حقل الموضوع الخاص به فارغا.
مخطط البيانات	معرف نموذج DTDL	dataschema = '<model-dtmi-ID>'	للقياس عن بعد: مخطط البيانات هو معرف طراز التوأم أو المكون الذي يرسل القياس عن بعد. على سبيل المثال، dtmi:example:com:floor4;2 بالنسبة للإعلامات (إنشاء/حذف): يمكن الوصول إلى مخطط البيانات في نص الإعلام في $body.$metadata.$model. بالنسبة للإعلامات (التحديث): يمكن الوصول إلى مخطط البيانات في نص الإعلام في $body.modelId
نوع المحتوى	نوع محتوى قيمة البيانات	datacontenttype = '<content-type>'	نوع المحتوى هو application/json
إصدار المواصفات	إصدار مخطط الحدث الذي تستخدمه	specversion = '<version>'	يجب أن يكون 1.0الإصدار . تشير هذه القيمة إلى إصدار مخطط CloudEvents 1.0
هيئة الإخطار	الرجوع إلى أي خاصية في data حقل إعلام	$body.<property>	راجع إعلامات الأحداث للحصول على أمثلة على الإعلامات. يمكن الرجوع إلى أي خاصية في data الحقل باستخدام $body

إشعار

لا يدعم Azure Digital Twins حاليا تصفية الأحداث استنادا إلى الحقول داخل صفيف. يتضمن ذلك التصفية على الخصائص داخل patch قسم من إعلام تغيير التوأم الرقمي.

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

نوع البيانات	مثال
السلسلة‬	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
رقم صحيح	$body.errorCode > 200
مزدوج	$body.temperature <= 5.5
مجموعة	$body.poweredOn = true
قيمة فارغة	$body.prop != null

يتم دعم العوامل التالية عند تحديد عوامل تصفية المسار:

العائلة	العوامل	مثال
منطقي	و، أو، ()	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
المقارنة	<، <=، >، >=، =، !=	$body.temperature <= 5.5

يتم دعم الوظائف التالية عند تحديد عوامل تصفية المسار:

الوظيفة	‏‏الوصف	مثال
STARTS_WITH(x,y)	إرجاع true إذا كانت القيمة x تبدأ بالسلسلة y.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y)	إرجاع true إذا انتهت القيمة x بالسلسلة y.	ENDS_WITH($body.$metadata.$model, 'floor;1')
تحتوي على (س، ص)	إرجاع true إذا كانت القيمة x تحتوي على السلسلة y.	CONTAINS(subject, '<twin-ID>')

عند تنفيذ أو تحديث عامل تصفية، قد يستغرق التغيير بضع دقائق لينعكس في تدفقات البيانات.

مراقبة مسارات الأحداث

يمكن عرض مقاييس التوجيه مثل العد وزمن الانتقال ومعدل الفشل في مدخل Microsoft Azure.

للحصول على معلومات حول عرض المقاييس وإدارتها باستخدام Azure Monitor، راجع بدء استخدام مستكشف المقاييس. للحصول على قائمة كاملة بمقاييس التوجيه المتوفرة ل Azure Digital Twins، راجع مقاييس توجيه Azure Digital Twins.

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

اقرأ عن الأنواع المختلفة لرسائل الأحداث التي يمكنك تلقيها:

• إعلامات الأحداث