تحليل النماذج والتحقق من صحتها باستخدام مكتبة محلل DTDL
توضح هذه المقالة كيفية تحليل نماذج Azure Digital Twins والتحقق من صحتها باستخدام نموذج مدقق DTDL أو مكتبة محلل .NET.
يتم تعريف النماذج في Azure Digital Twins باستخدام لغة تعريف التوائم الرقمية (DTDL) المستندة إلى JSON-LD. يوصى بالتحقق من صحة نماذجك في وضع عدم الاتصال قبل تحميلها إلى مثيل Azure Digital Twins.
لمساعدتك في التحقق من صحة النماذج الخاصة بك، يتم توفير مكتبة تحليل DTDL من جانب عميل .NET على NuGet: Microsoft.Azure.DigitalTwins.Parser.
يمكنك استخدام مكتبة المحلل اللغوي مباشرة في التعليمات البرمجية C # أو استخدام مشروع نموذج التعليمات البرمجية اللاأدرية باللغة المبني على مكتبة المحلل اللغوي: نموذج DTDL Validator.
استخدام نموذج مدقق DTDL
مدقق DTDL هو مشروع نموذجي يمكنه التحقق من صحة مستندات النموذج للتأكد من صلاحية DTDL. إنه مبني على مكتبة محلل .NET وهو لاأدري للغة.
يمكنك عرض التعليمات البرمجية في GitHub عن طريق تحديد الزر استعراض التعليمات البرمجية في الرابط النموذجي، ويمكنك تنزيل المشروع من GitHub عن طريق تحديد زر الرمز متبوعا بتنزيل الرمز البريدي.
تعرض التعليمات البرمجية المصدر أمثلة لكيفية استخدام مكتبة المحلل اللغوي. يمكنك استخدام نموذج المدقق كأداة مساعدة لسطر الأوامر للتحقق من صحة شجرة دليل من ملفات DTDL. كما يوفر وضعا تفاعليا.
في المجلد الخاص بنموذج DTDL Validator، راجع ملف readme.md للحصول على إرشادات حول كيفية حزم العينة في ملف قابل للتنفيذ قائم بذاته.
بعد إنشاء حزمة قائمة بذاتها وإضافة الملف القابل للتنفيذ إلى المسار الخاص بك، يمكنك تشغيل المدقق باستخدام هذا الأمر في وحدة تحكم على جهازك:
DTDLValidator
باستخدام الخيارات الافتراضية، سيبحث النموذج عن ملفات .json في الدليل الحالي وجميع الدلائل الفرعية. يمكنك أيضا إضافة الخيار التالي للحصول على نموذج البحث في الدليل المشار إليه وجميع الدلائل الفرعية للملفات ذات الامتداد .dtdl:
DTDLValidator -d C:\Work\DTDL -e dtdl
يمكنك إضافة خيار العينة للدخول في الوضع التفاعلي -i :
DTDLValidator -i
لمزيد من المعلومات حول هذه العينة، راجع التعليمات البرمجية المصدر أو تشغيل DTDLValidator --help.
استخدام مكتبة محلل .NET
توفر مكتبة Microsoft.Azure.DigitalTwins.Parser وصولا نموذجيا إلى تعريفات DTDL ، وتعمل بشكل أساسي كمكافئ لانعكاس C # ل DTDL. يمكن استخدام هذه المكتبة بشكل مستقل عن أي Azure Digital Twins SDK، خاصة للتحقق من صحة DTDL في محرر مرئي أو نصي. من المفيد التأكد من أن ملفات تعريف النموذج صالحة قبل محاولة تحميلها إلى الخدمة.
لاستخدام مكتبة المحلل اللغوي، يمكنك تزويدها بمجموعة من مستندات DTDL. عادة ، يمكنك استرداد هذه المستندات النموذجية من الخدمة ، ولكن قد تكون متاحة أيضا محليا ، إذا كان عميلك مسؤولا عن تحميلها إلى الخدمة في المقام الأول.
إليك سير العمل العام لاستخدام المحلل اللغوي:
- استرداد بعض أو كل مستندات DTDL من الخدمة.
- مرر مستندات DTDL التي تم إرجاعها في الذاكرة إلى المحلل اللغوي.
- سيقوم المحلل اللغوي بالتحقق من صحة مجموعة المستندات التي تم تمريرها إليه ، وإرجاع معلومات الخطأ التفصيلية. هذه القدرة مفيدة في سيناريوهات المحرر.
- استخدم واجهات برمجة تطبيقات المحلل اللغوي لمتابعة تحليل النماذج المضمنة في مجموعة المستندات.
تشمل قدرات المحلل اللغوي ما يلي:
- احصل على جميع واجهات النماذج المنفذة (محتويات قسم الواجهة
extends). - احصل على جميع الخصائص والقياس عن بعد والأوامر والمكونات والعلاقات المعلنة في النموذج. يحصل هذا الأمر أيضا على جميع بيانات التعريف المضمنة في هذه التعريفات ، ويأخذ الميراث (الأقسام
extends) في الاعتبار. - احصل على جميع تعريفات النماذج المعقدة.
- حدد ما إذا كان النموذج قابلا للتعيين من نموذج آخر.
ملاحظة
تستخدم أجهزة أجهزة التوصيل و التشغيل إنترنت الأشياء متغيرا صغيرا لبناء الجملة لوصف وظائفها. متغير بناء الجملة هذا هو مجموعة فرعية متوافقة دلاليا من DTDL المستخدمة في Azure Digital Twins. عند استخدام مكتبة المحلل اللغوي ، لا تحتاج إلى معرفة متغير بناء الجملة الذي تم استخدامه لإنشاء DTDL لتوأمك الرقمي. سيقوم المحلل اللغوي دائما ، افتراضيا ، بإرجاع نفس النموذج لكل من IoT أجهزة التوصيل و التشغيل وبناء جملة Azure Digital Twins.
التعليمات البرمجية باستخدام مكتبة المحلل اللغوي
يمكنك استخدام مكتبة المحلل اللغوي مباشرة، لأشياء مثل التحقق من صحة النماذج في تطبيقك الخاص أو لإنشاء واجهة مستخدم ديناميكية تعتمد على النموذج ولوحات معلومات وتقارير.
لدعم مثال التعليمات البرمجية للمحلل اللغوي أدناه، ضع في اعتبارك العديد من النماذج المعرفة في مثيل Azure Digital Twins:
[
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:contoso:coffeeMaker;1",
"@type": "Interface",
"contents": [
{
"@type": "Component",
"name": "coffeeMaker",
"schema": "dtmi:com:contoso:coffeeMakerInterface;1"
}
]
},
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:contoso:coffeeMakerInterface;1",
"@type": "Interface",
"contents": [
{
"@type": "Property",
"name": "waterTemp",
"schema": "double"
}
]
},
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:contoso:coffeeBar;1",
"@type": "Interface",
"contents": [
{
"@type": "Relationship",
"name": "foo",
"target": "dtmi:com:contoso:coffeeMaker;1"
},
{
"@type": "Property",
"name": "capacity",
"schema": "integer"
}
]
}
]
توضح التعليمة البرمجية التالية مثالا على كيفية استخدام مكتبة المحلل اللغوي للتفكير في هذه التعريفات في C #:
using Azure;
using Azure.DigitalTwins.Core;
using Microsoft.Azure.DigitalTwins.Parser;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace DigitalTwins_Samples
{
public class ParseModelsSample
{
public async Task ParseDemoAsync(DigitalTwinsClient client)
{
try
{
AsyncPageable<DigitalTwinsModelData> mdata = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });
var models = new List<string>();
await foreach (DigitalTwinsModelData md in mdata)
models.Add(md.DtdlModel);
var parser = new ModelParser();
IReadOnlyDictionary<Dtmi, DTEntityInfo> dtdlOM = await parser.ParseAsync(models);
var interfaces = new List<DTInterfaceInfo>();
IEnumerable<DTInterfaceInfo> ifenum =
from entity in dtdlOM.Values
where entity.EntityKind == DTEntityKind.Interface
select entity as DTInterfaceInfo;
interfaces.AddRange(ifenum);
foreach (DTInterfaceInfo dtif in interfaces)
{
PrintInterfaceContent(dtif, dtdlOM);
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"Failed due to {ex}");
throw;
}
}
public void PrintInterfaceContent(DTInterfaceInfo dtif, IReadOnlyDictionary<Dtmi, DTEntityInfo> dtdlOM, int indent = 0)
{
var sb = new StringBuilder();
for (int i = 0; i < indent; i++) sb.Append(" ");
Console.WriteLine($"{sb}Interface: {dtif.Id} | {dtif.DisplayName}");
Dictionary<string, DTContentInfo> contents = dtif.Contents;
foreach (DTContentInfo item in contents.Values)
{
switch (item.EntityKind)
{
case DTEntityKind.Property:
DTPropertyInfo pi = item as DTPropertyInfo;
Console.WriteLine($"{sb}--Property: {pi.Name} with schema {pi.Schema}");
break;
case DTEntityKind.Relationship:
DTRelationshipInfo ri = item as DTRelationshipInfo;
Console.WriteLine($"{sb}--Relationship: {ri.Name} with target {ri.Target}");
break;
case DTEntityKind.Telemetry:
DTTelemetryInfo ti = item as DTTelemetryInfo;
Console.WriteLine($"{sb}--Telemetry: {ti.Name} with schema {ti.Schema}");
break;
case DTEntityKind.Component:
DTComponentInfo ci = item as DTComponentInfo;
Console.WriteLine($"{sb}--Component: {ci.Id} | {ci.Name}");
DTInterfaceInfo component = ci.Schema;
PrintInterfaceContent(component, dtdlOM, indent + 1);
break;
}
}
}
}
}
الخطوات التالية
بمجرد الانتهاء من كتابة نماذجك، راجع كيفية تحميلها (والقيام بعمليات إدارة أخرى) باستخدام واجهات برمجة تطبيقات DigitalTwinsModels: