تعرف على النماذج المزدوجة وكيفية تعريفها في Azure Digital Twins

مقالة
01/04/2024

من السمات الرئيسية ل Azure Digital Twins القدرة على تحديد المفردات الخاصة بك وبناء الرسم البياني المزدوج الخاص بك في المصطلحات المعرفة ذاتيا لأعمالك. يتم توفير هذه الإمكانية من خلال النماذج التي يوفرها المستخدم. يمكنك التفكير في النماذج على أنها الأسماء في وصف لعالمك. يتم تمثيل نماذج Azure Digital Twins بلغة تعريف التوأم الرقمي (DTDL) المستندة إلى JSON-LD.

يشبه النموذج فئة في لغة برمجة موجهة للكائنات، ويحدد شكل بيانات لمفهوم معين واحد في بيئة العمل الحقيقية الخاصة بك. تحتوي النماذج على أسماء (مثل Room أو TemperatureSensor)، وتحتوي على عناصر مثل الخصائص والمكونات والعلاقات التي تصف ما يفعله هذا النوع من الكيانات في بيئتك. لاحقا، ستستخدم هذه النماذج لإنشاء توائم رقمية تمثل كيانات محددة تفي بوصف هذا النوع.

لغة تعريف التوأم الرقمي (DTDL) للنماذج

يتم تعريف نماذج Azure Digital Twins باستخدام لغة تعريف التوائم الرقمية (DTDL).

يمكنك عرض وصف اللغة الكامل ل DTDL v3 في GitHub: وصف لغة DTDL الإصدار 3. تتضمن هذه الصفحة تفاصيل وأمثلة مرجعية ل DTDL لمساعدتك على البدء في كتابة نماذج DTDL الخاصة بك.

وتعتمد DTDL على JSON-LD وهي لغة برمجة مستقلة. DTDL ليست حصرية ل Azure Digital Twins. كما يتم استخدامه لتمثيل بيانات الجهاز في خدمات IoT الأخرى مثل IoT أجهزة التوصيل و التشغيل.

تلخص بقية هذه المقالة كيفية استخدام اللغة في Azure Digital Twins.

إصدارات DTDL المدعومة

يدعم Azure Digital Twins الإصدارين 2 و3 من DTDL (تم اختصارهما في الوثائق إلى v2 وv3، على التوالي). V3 هو الخيار الموصى به للنمذجة في Azure Digital Twins استنادا إلى قدراته الموسعة، بما في ذلك:

استرخاء إصدار DTMI
دعم الصفيف للخصائص
زيادة حدود توريث النموذج
ملحقات الميزات
- القدرة على تزيين مخططات الواجهة المخصصة بالأنواع الدلالية (المقدمة مع ملحق الالأنواع الكمية)

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

يدعم Azure Digital Twins أيضا استخدام مزيج من نماذج v2 وv3 داخل نفس المثيل. عند استخدام نماذج كلا الإصدارين معا، ضع في اعتبارك القيود التالية:

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

يمكنك أيضا ترحيل نماذج v2 الموجودة إلى v3. للحصول على إرشادات حول كيفية القيام بذلك، راجع تحويل نماذج v2 إلى v3.

إشعار

حاليا، يدعم Azure Digital Twins Explorer نماذج DTDL v2 بشكل كامل ويدعم وظائف محدودة لنماذج DTDL v3. في Azure Digital Twins Explorer، يمكن عرض نماذج DTDL v3 في لوحة Models، ويمكن عرض التوائم التي تم إنشاؤها باستخدام نماذج DTDL v3 وتحريرها (بما في ذلك تلك ذات خصائص الصفيف). ومع ذلك، لن تظهر نماذج DTDL v3 في لوحة Model Graph، ولا يمكن استيرادها باستخدام Azure Digital Twins Explorer. لاستيراد نماذج DTDL v3 إلى المثيل الخاص بك، استخدم واجهة مطور أخرى مثل واجهات برمجة التطبيقات وSDKs أو Azure CLI.

نظرة عامة على النموذج

يمكن كتابة نماذج نوع مزدوج في أي محرر نص. تتبع لغة DTDL بناء جملة JSON، لذلك يجب تخزين النماذج مع .json الملحق. استخدام ملحق JSON سيمكن العديد من برامج تحرير نصوص البرمجة من توفير فحص بناء الجملة الأساسي و تمييز مستندات لغة تعريف التوأم الرقمي. هناك أيضا ملحق DTDL متاح ل Visual Studio Code.

فيما يلي الحقول داخل واجهة نموذج:

الحقل	‏‏الوصف
`@id`	معرف نموذج Digital Twin (DTMI) للنموذج، بالتنسيق `dtmi:<domain>:<unique-model-identifier>;<model-version-number>`. في DTDL v3، يمكن حذف رقم الإصدار أو تنظيمه كرقم إصدار من جزئين (`<major>.<minor>`).
`@type`	يحدد نوع المعلومات التي يتم وصفها. بالنسبة للواجهة، يكون النوع هو `Interface`.
`@context`	تعيين سياق مستند JSON. يجب استخدام `dtmi:dtdl:context;2` النماذج ل DTDL v2، أو `dtmi:dtdl:context;3` ل DTDL v3. يمكن لنماذج DTDL v3 أيضا تسمية ملحقات الميزات الإضافية في هذا الحقل.
`displayName`	[اختياري] يمنحك خيار تحديد اسم مألوف للنموذج. إذا لم تستخدم هذا الحقل، فسيستخدم النموذج قيمته DTMI الكاملة.
`contents`	يتم وضع كافة البيانات المتبقية واجهة هنا، كصفيفة من تعريفات السمة. يجب أن توفر كل سمة `@type` (`Property`أو `Relationship`أو `Component`) لتحديد نوع معلومات الواجهة التي تصفها، ثم مجموعة من الخصائص التي تحدد السمة الفعلية. يصف القسم التالي سمات النموذج بالتفصيل.

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

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

سمات النموذج

يتم إعطاء المعلومات الرئيسية حول النموذج من خلال سماته، والتي يتم تعريفها داخل contents قسم واجهة النموذج.

فيما يلي السمات المتوفرة في DTDL المدعومة في Azure Digital Twins. قد تحتوي واجهة نموذج DTDL المستخدمة ل Azure Digital Twins على صفر أو واحد أو العديد من كل حقل من الحقول التالية:

الخاصية - الخصائص هي حقول بيانات تمثل حالة الكيان (مثل الخصائص في العديد من لغات البرمجة الموجهة للعناصر). لدى الخصائص تخزين النسخ الاحتياطي ويمكن قراءتها في أي وقت. لمزيد من المعلومات، راجع الخصائص أدناه.
العلاقة - تتيح لك العلاقات تمثيل كيفية مشاركة التوأم الرقمي مع التوائم الرقمية الأخرى. يمكن أن تمثل العلاقات معاني دلالية مختلفة، مثل contains ("الأرضية تحتوي على غرفة")، cools ("hvac cools room")، isBilledTo ("يتم فوترة الضاغط للمستخدم")، وما إلى ذلك. تسمح العلاقات للحل بتوفير رسم بياني للكيانات المترابطة. يمكن أن يكون للعلاقات أيضا خصائص خاصة بها. لمزيد من المعلومات، راجع العلاقات أدناه.
المكون - تسمح لك المكونات بإنشاء واجهة النموذج الخاصة بك كتجمع للواجهات الأخرى، إذا كنت تريد ذلك. مثال على المكون هو واجهة أمامية الكاميرا (وواجهة مكون أخرى مرة أخرى الكاميرا) تستخدم في تعريف نموذج لهاتف. أولا حدد واجهة للواجهة الأمامية الكاميرا كما لو كانت نموذجها الخاص، ثم قم بالإشارة إليها عند تعريف الهاتف.

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

تلميح

يمكن أيضا استخدام المكونات للمؤسسة، لتجميع مجموعات من الخصائص ذات الصلة داخل واجهة نموذج. في هذه الحالة، يمكنك التفكير في كل مكون كمساحة اسم أو "مجلد" داخل الواجهة.

لمزيد من المعلومات، راجع المكونات أدناه.

يعرف وصف اللغة DTDL v3 أيضا الأوامر وبيانات تتبع الاستخدام، ولكن لا يتم استخدام أي منهما في Azure Digital Twins. الأوامر غير مدعومة، ولا يحتوي القياس عن بعد - على الرغم من أنه مسموح به في تعريفات النموذج - على حالة استخدام فريدة في نمذجة Azure Digital Twins. بدلا من استخدام بيانات تتبع الاستخدام DTDL، يجب استخدام خصائص DTDL لتخزين معلومات الحالة المزدوجة.

إشعار

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

خصائص

يتناول هذا القسم المزيد من التفاصيل حول الخصائص في نماذج DTDL.

للحصول على معلومات شاملة حول الحقول التي قد تظهر كجزء من خاصية، راجع الخاصية في وصف اللغة DTDL v3.

إشعار

writable السمة DTDL للخصائص غير مدعومة حاليا في Azure Digital Twins. يمكن إضافته إلى النموذج، ولكن لن يفرضه Azure Digital Twins. لمزيد من المعلومات، راجع ملاحظات DTDL الخاصة بالخدمة.

مخطط

وفقا ل DTDL، يمكن أن يكون مخطط سمات الخاصية نوعا بدائيا قياسيا —integer و doublebooleanstring— وأنواعا أخرى مثل dateTime و.duration

بالإضافة إلى الأنواع الأولية، يمكن أن تحتوي حقول الخصائص على هذه الأنواع المعقدة:

Object
Map
Enum
Array، في DTDL v3 فقط. Array نوع الخصائص غير معتمد في DTDL v2.

يمكن أن تكون أيضا أنواعا دلالية، والتي تسمح لك بتعليق القيم بالوحدات. في DTDL v2، يتم دعم الأنواع الدلالية في الأصل؛ في DTDL v3، يمكنك تضمينها مع ملحق ميزة.

مثال على الخاصية الأساسية

فيما يلي مثال أساسي لخاصية على نموذج DTDL. يوضح هذا المثال خاصية معرف الصفحة الرئيسية.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

مثال على نوع الكائن المعقد

يمكن أن تكون الخصائص من أنواع معقدة، بما في ذلك Object النوع.

يوضح المثال التالي إصدارا آخر من نموذج Home، مع خاصية لعنوانه. address هو كائن، مع حقوله الخاصة للشارع والمدينة والولاية والرمز البريدي.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

مثال على النوع الدلالي DTDL v2

الأنواع الدلالية هي للتعبير عن قيمة مع وحدة. يمكن لخصائص Azure Digital Twins استخدام أي من الأنواع الدلالية التي يدعمها DTDL.

في DTDL v2، يتم دعم الأنواع الدلالية في الأصل. لمزيد من المعلومات حول الأنواع الدلالية في DTDL v2، راجع الأنواع الدلالية في وصف اللغة DTDL v2. للتعرف على الأنواع الدلالية في DTDL v3، راجع ملحق ميزة الأنواع الكمية DTDL v3.

يوضح المثال التالي نموذج مستشعر DTDL v2 مع خصائص النوع الدلالي للرطوبة ودرجة الحرارة.

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Property", "Temperature"],
      "name": "Temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "Humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

هام

يجب أن تكون "الخاصية" العنصر الأول من @type الصفيف، متبوعا بنوع الدلالي. وإلا، قد لا يكون الحقل مرئيا في Azure Digital Twins Explorer.

العلاقات

يتناول هذا القسم المزيد من التفاصيل حول العلاقات في نماذج DTDL.

للحصول على قائمة شاملة بالحقول التي قد تظهر كجزء من علاقة، راجع العلاقة في وصف اللغة DTDL v3.

إشعار

writableminMultiplicityالسمات و و maxMultiplicity DTDL للعلاقات غير مدعومة حاليا في Azure Digital Twins. يمكن إضافتها إلى النموذج، ولكن لن يفرضها Azure Digital Twins. لمزيد من المعلومات، راجع ملاحظات DTDL الخاصة بالخدمة.

مثال على العلاقة الأساسية

فيما يلي مثال أساسي على علاقة على نموذج DTDL. يوضح هذا المثال علاقة على نموذج Home تسمح له بالاتصال بنموذج Floor.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

إشعار

بالنسبة للعلاقات، @id هو حقل اختياري. إذا لم يتم توفيره @id ، فسيعين معالج واجهة التوأم الرقمي واحدا.

العلاقات المستهدفة وغير المستهدفة

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

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

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

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"

خصائص العلاقات

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

يوضح المثال التالي إصدارا آخر من نموذج Home، حيث تحتوي العلاقة rel_has_floors على خاصية تمثل عند آخر شغل للطابق ذي الصلة.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

المكونات

يتناول هذا القسم المزيد من التفاصيل حول المكونات في نماذج DTDL.

للحصول على قائمة شاملة بالحقول التي قد تظهر كجزء من مكون، راجع المكون في وصف اللغة DTDL v3.

مثال المكون الأساسي

فيما يلي مثال أساسي لمكون على نموذج DTDL. يوضح هذا المثال نموذج Room الذي يستخدم نموذج منظم الحرارة كمكون.

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

إذا كانت النماذج الأخرى في هذا الحل يجب أن تحتوي أيضا على منظم حرارة، فإنها يمكن أن تشير إلى نفس نموذج منظم الحرارة كمكون في تعريفاتها الخاصة، تماما كما يفعل Room.

هام

يجب تعريف واجهة المكون (منظم الحرارة في المثال أعلاه) في نفس الصفيف مثل أي واجهات تستخدمه (الغرفة في المثال أعلاه) من أجل العثور على مرجع المكون.

اكتساب النموذج

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

القسم extends هو اسم واجهة أو صفيف من أسماء الواجهة (يسمح للواجهة الموسعة بالتوارث من نماذج أصل متعددة). يمكن أن يعمل أحد الوالدين الفرديين كنموذج أساسي لواجهات توسيع متعددة.

إشعار

في DTDL v2، يمكن أن يكون لكل extends منهما واجهتين مدرجتين له على الأكثر. في DTDL v3، لا يوجد حد لعدد القيم الفورية extendsل .

في كل من DTDL v2 وv3، يكون حد العمق الإجمالي للتسلسل extends الهرمي هو 10.

يعيد المثال التالي تخيل نموذج Home من مثال DTDL السابق كنوع فرعي لنموذج "أساسي" أكبر. يتم تعريف النموذج الأصل (Core) أولا، ثم يقوم النموذج التابع (Home) بالبناء عليه باستخدام extends.

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

في هذه الحالة، تساهم Core بمعرف واسم إلى Home. يمكن للنماذج الأخرى أيضا توسيع النموذج الأساسي للحصول على هذه الخصائص أيضا. فيما يلي نموذج غرفة يوسع نفس الواجهة الأصلية:

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",

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

لا يمكن للواجهة الموسعة تغيير أي من تعريفات الواجهات الأصل؛ يمكن أن تضيف إليها فقط. كما أنه لا يمكنه إعادة تعريف إمكانية محددة بالفعل في أي من واجهاتها الأصلية (حتى إذا تم تعريف القدرات لتكون هي نفسها). على سبيل المثال، إذا كانت الواجهة الأصل تحدد double خاصية mass، فلا يمكن أن تحتوي الواجهة الموسعة على إعلان ، massحتى لو كانت أيضا double.

ملحقات ميزات DTDL v3

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

يتم تحديد كل ملحق ميزة بواسطة محدد السياق الخاص به، وهو قيمة معرف نموذج Digital Twin فريدة (DTMI). لتمكين ملحق ميزة في نموذج، أضف محدد سياق الملحق إلى حقل النموذج @context (جنبا إلى جنب مع محدد سياق DTDL العام ل dtmi:dtdl:context;3). يمكنك إضافة ملحقات ميزات متعددة إلى نفس النموذج.

فيما يلي مثال لما قد يبدو عليه هذا @context الحقل مع ملحقات الميزات. المقتطف التالي من نموذج يستخدم كل من ملحق النماذج الكمية وملحق التعليق التوضيحي.

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

بعد إضافة ملحق ميزة إلى نموذج، سيكون لديك حق الوصول إلى الأنواع الملحقة لهذا الملحق داخل النموذج. يمكنك إضافة أنواع ملحقة @type إلى حقل عنصر DTDL، لمنح العنصر قدرات إضافية. قد يضيف النوع الملحق خصائص إضافية إلى العنصر.

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

{
  "@type": [ "Property", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

يشرح الجزء المتبقي من هذا القسم ملحق التعليق التوضيحي وملحقات ميزات DTDL v3 الأخرى بمزيد من التفصيل.

ملحق التعليق التوضيحي

يتم استخدام ملحق التعليق التوضيحي لإضافة بيانات تعريف مخصصة إلى عنصر خاصية في نموذج DTDL v3. محدد السياق الخاص به هو dtmi:dtdl:extension:annotation;1.

يتضمن ValueAnnotation هذا الملحق النوع الملحق، والذي يمكن إضافته إلى عنصر خاصية DTDL. ValueAnnotation يضيف النوع حقلا واحدا إلى العنصر ، annotatesوالذي يسمح لك بتسمية خاصية أخرى مشروحة بالعنصر الحالي.

لمزيد من التفاصيل والأمثلة لهذا الملحق، راجع ملحق التعليق التوضيحي في وصف اللغة DTDL v3.

ملحق الامتداد التكراري

يتم استخدام ملحق المحفوظات لتعيين خاصية في نموذج DTDL v3 كشيء يجب أن يتم تأريخه (بمعنى أنه يجب تسجيل التسلسل التاريخي لقيمه، جنبا إلى جنب مع الأوقات التي تتغير فيها القيم). محدد السياق الخاص به هو dtmi:dtdl:extension:historization;1.

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

لمزيد من التفاصيل والأمثلة على هذا الملحق، راجع ملحق التكرار في وصف اللغة DTDL v3.

تجاوز الملحق

يتم استخدام ملحق التجاوز لتجاوز خاصية في نموذج DTDL V3 بقيمة مثيل. يتم استخدامه بالاشتراك مع ملحق التعليق التوضيحي، ومحدد السياق الخاص به هو dtmi:dtdl:extension:overriding;1.

يتضمن Override هذا الملحق النوع الملحق، والذي يمكن إضافته إلى خاصية DTDL التي يتم أيضا كتابتها بشكل مشترك مع ValueAnnotation (من ملحق التعليق التوضيحي). Override يضيف النوع حقلا واحدا إلى العنصر ، overridesوالذي يسمح لك بتسمية حقل على العنصر الذي تمت إضافته إلى التعليق التوضيحي ليتم تجاوزه بقيمة العنصر الحالي.

لمزيد من التفاصيل والأمثلة على هذا الملحق، راجع تجاوز الملحق في وصف اللغة DTDL v3.

ملحق النماذج الكمية

يتم استخدام ملحق الالأنواع الكمية لتمكين الأنواع الدلالية وأنواع الوحدات والوحدات في نموذج DTDL v3. محدد السياق الخاص به هو dtmi:dtdl:extension:quantitativeTypes;1.

يتيح هذا الملحق استخدام العديد من الأنواع الدلالية كالأنواع الملحقة، والتي يمكن إضافتها إلى CommandRequest أو حقل أو MapValue أو خاصية في DTDL v3. تضيف الأنواع الدلالية حقلا واحدا إلى العنصر ، unitوالذي يقبل وحدة صالحة تتوافق مع النوع الدلالي.

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

ملاحظات DTDL الخاصة بالخدمة

لا تقوم كافة الخدمات التي تستخدم لغة تعريف التوأم الرقمي بتطبيق نفس الميزات بالضبط بلغة تعريف التوأم الرقمي. هناك بعض ميزات DTDL التي لا يدعمها Azure Digital Twins حاليا، بما في ذلك:

أوامر DTDL
السمة writable على الخصائص أو العلاقات. على الرغم من أنه يمكن تعيين هذه السمة وفقا لمواصفات DTDL، لا يتم استخدام القيمة من قبل Azure Digital Twins. بدلا من ذلك، يتم التعامل مع هذه السمات دائما على أنها قابلة للكتابة من قبل العملاء الخارجيين الذين لديهم أذونات كتابة عامة لخدمة Azure Digital Twins.
خصائص minMultiplicity و maxMultiplicity على العلاقات. على الرغم من أنه يمكن تعيين هذه السمات وفقا لمواصفات DTDL، لا يتم فرض القيم بواسطة Azure Digital Twins.

لكي يكون نموذج DTDL متوافقا مع Azure Digital Twins، يجب أن يفي أيضا بهذه المتطلبات:

يجب أن تكون جميع عناصر DTDL ذات المستوى الأعلى في النموذج من النوع Interface. والسبب في هذا المطلب هو أن واجهات برمجة تطبيقات نموذج Azure Digital Twins يمكن أن تتلقى كائنات JSON التي تمثل واجهة أو صفيف من الواجهات. ونتيجة لذلك، يسمح أية أنواع عناصر لغة تعريف التوأم الرقمي أخرى في المستوى الأعلى.
يجب أن لا يُعرف لغة تعريف التوأم الرقمي بـ Azure Digital Twins أية أوامر.
يسمح Azure Digital Twins بمستوى واحد فقط من تداخل المكونات، ما يعني أن الواجهة التي يتم استخدامها كمكون لا يمكن أن تحتوي على أي مكونات بحد ذاتها.
لا يمكن تعريف الواجهات مضمنة داخل واجهات لغة تعريف التوأم الرقمي أخرى; يجب تعريفها ككيانات منفصلة على مستوى عال مع معرفاتها الخاصة. ثم، عندما تريد واجهة أخرى تضمين تلك الواجهة كمكون أو من خلال الاكتساب، يمكن الرجوع إلى المعرِّف الخاص بها.

أدوات النمذجة وأفضل الممارسات

يصف هذا القسم اعتبارات وتوصيات إضافية للنمذجة.

استخدام مقاييس الصناعة الحالية

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

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

النظر في الآثار المترتبة على الاستعلام

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

التحقق من صحة النماذج

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

لمساعدتك في التحقق من صحة النماذج الخاصة بك، يتم توفير مكتبة تحليل DTDL من جانب عميل .NET على NuGet: DTDLParser. يمكنك استخدام مكتبة المحلل مباشرة في التعليمات البرمجية C#. يمكنك أيضا عرض نموذج استخدام المحلل في DTDLParserResolveSample في GitHub.

تحميل النماذج وحذفها بشكل مجمع

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

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

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

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

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

تصور النماذج

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

إشعار

فيما يلي مثال على الشكل الذي قد يبدو عليه الرسم البياني النموذجي:

لمزيد من المعلومات حول تجربة النموذج في Azure Digital Twins Explorer، راجع استكشاف النماذج ونموذج الرسم البياني.

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

تعرف على كيفية إنشاء نماذج تستند إلى طبولوجيا قياسية في الصناعة: ما هو علم الأورام؟
التعمق في إدارة النماذج باستخدام عمليات واجهة برمجة التطبيقات: إدارة نماذج DTDL
تعرف على كيفية استخدام النماذج لإنشاء توائم رقمية: التوائم الرقمية والرسم البياني المزدوج

تعرف على النماذج المزدوجة وكيفية تعريفها في Azure Digital Twins

لغة تعريف التوأم الرقمي (DTDL) للنماذج

إصدارات DTDL المدعومة

نظرة عامة على النموذج

سمات النموذج

خصائص

مخطط

مثال على الخاصية الأساسية

مثال على نوع الكائن المعقد

مثال على النوع الدلالي DTDL v2

العلاقات

مثال على العلاقة الأساسية

العلاقات المستهدفة وغير المستهدفة

خصائص العلاقات

المكونات

مثال المكون الأساسي

اكتساب النموذج

ملحقات ميزات DTDL v3

ملحق التعليق التوضيحي

ملحق الامتداد التكراري

تجاوز الملحق

ملحق النماذج الكمية

ملاحظات DTDL الخاصة بالخدمة

أدوات النمذجة وأفضل الممارسات

استخدام مقاييس الصناعة الحالية

النظر في الآثار المترتبة على الاستعلام

التحقق من صحة النماذج

تحميل النماذج وحذفها بشكل مجمع

تصور النماذج

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

الموارد الإضافية