إدارة نماذج Azure Digital Twins

توضح هذه المقالة كيفية إدارة النماذج في مثيل Azure Digital Twins. تتضمن عمليات الإدارة تحميل النماذج والتحقق من صحتها واستردادها وحذفها.

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

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

بعد إعداد المثيل الخاص بك، دون اسم مضيف المثيل. يمكنك العثور على اسم المضيف في بوابة Azure.

واجهات المطور

تسلط هذه المقالة الضوء على كيفية إكمال عمليات الإدارة المختلفة باستخدام .NET (C#) SDK. يمكنك أيضا صياغة استدعاءات الإدارة نفسها هذه باستخدام حزم SDK للغة الأخرى الموضحة في واجهات برمجة تطبيقات Azure Digital Twins وSDKs.

تتضمن واجهات المطور الأخرى التي يمكن استخدامها لإكمال هذه العمليات ما يلي:

• مستكشف Azure Digital Twins
• استدعاءات REST API
• أوامر Azure CLI

الرسوم المرئية

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

للقراءة عن أداة Azure Digital Twins Explorer، راجع Azure Digital Twins Explorer. للحصول على خطوات مفصلة حول كيفية استخدام ميزاته، راجع استخدام Azure Digital Twins Explorer.

إليك الشكل الذي تبدو عليه المرئيات:

إنشاء نماذج

يمكنك إنشاء نماذجك الخاصة من البداية، أو استخدام النماذج الموجودة المتوفرة لمجالك.

نماذج المؤلف

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

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

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

{
    "@id": "dtmi:com:contoso:PatientRoom;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Patient Room",
    "contents": [
      {
        "@type": "Property",
        "name": "visitorCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashCount",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "handWashPercentage",
        "schema": "double"
      },
      {
        "@type": "Relationship",
        "name": "hasDevices"
      }
    ]
  }

إشعار

هذا نص نموذجي لملف JSON يتم فيه تعريف النموذج وحفظه، ليتم تحميله كجزء من مشروع عميل. من ناحية أخرى، يأخذ استدعاء REST API صفيفا من تعريفات النموذج مثل التعريف أعلاه (الذي تم تعيينه إلى IEnumerable<string> في .NET SDK). لذلك لاستخدام هذا النموذج في واجهة برمجة تطبيقات REST مباشرة، قم بإحاطته بأقواس.

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

إشعار

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

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

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

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

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

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

التحقق من صحة بناء الجملة

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

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

نماذج التحميل

بمجرد إنشاء النماذج، يمكنك تحميلها إلى مثيل Azure Digital Twins.

عندما تكون مستعدا لتحميل نموذج، يمكنك استخدام مقتطف التعليمات البرمجية التالي ل .NET SDK:

// 'client' is an instance of DigitalTwinsClient
// Read model file into string (not part of SDK)
// fileName is the name of the JSON model file
string dtdl = File.ReadAllText(fileName);
await client.CreateModelsAsync(new[] { dtdl });

عند التحميل، يتم التحقق من صحة ملفات النموذج بواسطة الخدمة.

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

تحميل مجموعات نماذج صغيرة

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

إذا كنت تستخدم SDK، يمكنك تحميل ملفات نماذج متعددة باستخدام CreateModels أسلوب مثل هذا:

var dtdlFiles = Directory.EnumerateFiles(sourceDirectory, "*.json");

var dtdlModels = new List<string>();
foreach (string fileName in dtdlFiles)
{
    // Read model file into string (not part of SDK)
    string dtdl = File.ReadAllText(fileName);
    dtdlModels.Add(dtdl);
}
await client.CreateModelsAsync(dtdlModels);

إذا كنت تستخدم واجهات برمجة تطبيقات REST أو Azure CLI، يمكنك تحميل نماذج متعددة عن طريق وضع تعريفات نماذج متعددة في ملف JSON واحد لتحميله معا. في هذه الحالة، يجب وضع النماذج في صفيف JSON داخل الملف، كما في المثال التالي:

[
    {
      "@id": "dtmi:com:contoso:Planet;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    },
    {
      "@id": "dtmi:com:contoso:Moon;1",
      "@type": "Interface",
      "@context": "dtmi:dtdl:context;3"
    }
]

تحميل مجموعات نماذج كبيرة باستخدام واجهة برمجة تطبيقات استيراد المهام

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

تلميح

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

لاستيراد النماذج بشكل مجمع، ستحتاج إلى هيكلة نماذجك (وأي موارد أخرى مضمنة في مهمة الاستيراد المجمع) كملف NDJSON . Models يأتي القسم مباشرة بعد Header المقطع، مما يجعله أول قسم لبيانات الرسم البياني في الملف. يمكنك عرض مثال لملف استيراد ومشروع عينة لإنشاء هذه الملفات في مقدمة واجهة برمجة تطبيقات استيراد المهام.

بعد ذلك، يجب تحميل الملف إلى كائن ثنائي كبير الحجم للإلحاق في Azure Blob Storage. للحصول على إرشادات حول كيفية إنشاء حاوية تخزين Azure، راجع إنشاء حاوية. ثم قم بتحميل الملف باستخدام أسلوب التحميل المفضل لديك (بعض الخيارات هي الأمر AzCopy أو Azure CLI أو مدخل Microsoft Azure).

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

فيما يلي لقطة شاشة تعرض قيمة عنوان URL لملف كائن ثنائي كبير الحجم في مدخل Microsoft Azure:

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

استرداد النماذج

يمكنك سرد واسترداد النماذج المخزنة على مثيل Azure Digital Twins.

تتضمن خياراتك ما يلي:

• استرداد نموذج واحد
• استرداد جميع النماذج
• استرداد بيانات التعريف والتبعيات للنماذج

فيما يلي بعض الأمثلة على المكالمات:

// 'client' is a valid DigitalTwinsClient object

// Get a single model, metadata and data
Response<DigitalTwinsModelData> md1 = await client.GetModelAsync("<model-Id>");
DigitalTwinsModelData model1 = md1.Value;

// Get a list of the metadata of all available models; print their IDs
AsyncPageable<DigitalTwinsModelData> md2 = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in md2)
{
    Console.WriteLine($"Type ID: {md.Id}");
}

// Get models and metadata for a model ID, including all dependencies (models that it inherits from, components it references)
AsyncPageable<DigitalTwinsModelData> md3 = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });

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

RetrieveModelWithDependencies لا يرجع الاستدعاء النموذج المطلوب فقط، ولكن أيضا جميع النماذج التي يعتمد عليها النموذج المطلوب.

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

تحديث النماذج

يصف هذا القسم الاعتبارات والاستراتيجيات لتحديث نماذجك.

قبل التحديث: فكر في سياق الحل بأكمله

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

فيما يلي بعض التوصيات لمساعدتك في إدارة انتقالات النموذج بسلاسة:

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

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

استراتيجيات لتحديث النماذج

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

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

هناك إستراتيجيتان للاختيار من بينهما عند استبدال نموذج:

• الاستراتيجية 1: تحميل إصدار نموذج جديد: تحميل النموذج، مع رقم إصدار جديد، وتحديث التوائم لاستخدام هذا النموذج الجديد. سيوجد كل من الإصدارين الجديد والقديم من النموذج في المثيل الخاص بك حتى تقوم بحذف واحد.
  • استخدم هذه الاستراتيجية عندما تريد تحديث بعض التوائم فقط التي تستخدم النموذج، أو عندما تريد التأكد من أن التوائم تظل متوافقة مع نماذجها وقابلة للكتابة من خلال انتقال النموذج.
• الاستراتيجية 2: حذف النموذج القديم وإعادة تحميله: احذف النموذج الأصلي وحمل النموذج الجديد بنفس الاسم والمعرف (قيمة DTMI) في مكانه. يستبدل النموذج القديم تماما بالنموذج الجديد.
  • استخدم هذه الاستراتيجية عندما تريد تحديث جميع التوائم التي تستخدم هذا النموذج في وقت واحد، بالإضافة إلى جميع التعليمات البرمجية التي تتفاعل مع النماذج. إذا كان تحديث النموذج الخاص بك يحتوي على تغيير فاصل مع تحديث النموذج، فإن التوائم ستكون غير متوافقة مع نماذجها لفترة قصيرة أثناء نقلها من النموذج القديم إلى النموذج الجديد، ما يعني أنها لن تكون قادرة على إجراء أي تحديثات حتى يتم تحميل النموذج الجديد والتوائم تتوافق معه.

إشعار

لا ينصح بإجراء تغييرات كسرية على نماذجك خارج التطوير.

تابع إلى الأقسام التالية لقراءة المزيد حول كل خيار استراتيجية بالتفصيل.

الاستراتيجية 1: تحميل إصدار نموذج جديد

يتضمن هذا الخيار إنشاء إصدار جديد من النموذج وتحميله إلى المثيل الخاص بك.

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

لاستخدام هذه الاستراتيجية، اتبع الخطوات أدناه.

1. إنشاء وتحميل إصدار نموذج جديد

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

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

على سبيل المثال، إذا كان معرف الطراز السابق يبدو هكذا:

"@id": "dtmi:com:contoso:PatientRoom;1",

قد يبدو الإصدار 2 من هذا النموذج كما يلي:

"@id": "dtmi:com:contoso:PatientRoom;2",

ثم قم بتحميل الإصدار الجديد من النموذج إلى المثيل الخاص بك.

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

2. تحديث عناصر الرسم البياني حسب الحاجة

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

يمكنك استخدام الإرشادات التالية لتحديث التوائم وتحديث العلاقات. ستبدو عملية التصحيح لتحديث نموذج التوأم كما يلي:

[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:example:foo;1"
  }
]

هام

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

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

3. (اختياري) إيقاف تشغيل إصدار النموذج القديم أو حذفه

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

يمكنك أيضا حذف النموذج القديم تماما إذا كنت لا تريد ذلك في المثيل بعد الآن على الإطلاق.

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

الاستراتيجية 2: حذف النموذج القديم وإعادة التحميل

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

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

لاستخدام هذه الاستراتيجية، اتبع الخطوات أدناه.

1. حذف النموذج القديم

نظرا لأن Azure Digital Twins لا يسمح بنموذجين بنفس المعرف، ابدأ بحذف النموذج الأصلي من المثيل الخاص بك.

إشعار

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

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

2. إنشاء نموذج جديد وتحميله

ابدأ ب DTDL للنموذج الأصلي. قم بتحديث الحقول التي تريد تغييرها أو إضافتها أو إزالتها.

ثم قم بتحميل النموذج إلى المثيل، كما لو كان نموذجا جديدا يتم تحميله للمرة الأولى.

3. تحديث عناصر الرسم البياني حسب الحاجة

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

إشعار

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

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

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

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

إزالة النماذج

يمكن إزالة النماذج من الخدمة بإحدى طريقتين:

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

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

إشعار

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

وقف التشغيل

لإيقاف تشغيل نموذج، يمكنك استخدام أسلوب DecommissionModel من SDK:

// 'client' is a valid DigitalTwinsClient
await client.DecommissionModelAsync(dtmiOfPlanetInterface);
// Write some code that deletes or transitions digital twins
//...

يمكنك أيضا إيقاف تشغيل نموذج باستخدام استدعاء واجهة برمجة تطبيقات REST DigitalTwinModels Update. decommissioned الخاصية هي الخاصية الوحيدة التي يمكن استبدالها باستدعاء API هذا. سيبدو مستند JSON Patch كما يلي:

[
  {
    "op": "replace",
    "path": "/decommissioned",
    "value": true
  }
]

يتم تضمين حالة إيقاف تشغيل النموذج في السجلات التي ModelData تم إرجاعها بواسطة واجهات برمجة تطبيقات استرداد النموذج.

حذف

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

للحصول على مثال حول كيفية حذف جميع النماذج في نفس الوقت، راجع العينات الشاملة لمستودع Azure Digital Twins في GitHub. يحتوي ملف CommandLoop.cs على دالة CommandDeleteAllModels مع تعليمات برمجية لحذف كافة النماذج في المثيل.

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

قبل الحذف: متطلبات الحذف

بشكلٍ عام، يمكن حذف النماذج في أي وقت.

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

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

أثناء الحذف: عملية الحذف

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

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

لحذف نموذج، يمكنك استخدام استدعاء DeleteModel SDK:

// 'client' is a valid DigitalTwinsClient
await client.DeleteModelAsync(IDToDelete);

يمكنك أيضا حذف نموذج باستخدام استدعاء DigitalTwinModels Delete REST API.

بعد الحذف: توأمان بدون نماذج

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

فيما يلي نظرة عامة على ما يمكنك وما لا يمكنك فعله مع الأزواج التي ليس لها نموذج.

أشياء يمكنك فعلها:

• الاستعلام عن التوأم
• قراءة الخصائص
• قراءة العلاقات الصادرة
• إضافة وحذف العلاقات الواردة (كما في، لا يزال بإمكان التوائم الأخرى تشكيل علاقات مع هذا التوأم)
  • target لا يزال بإمكان تعريف العلاقة أن يعكس DTMI للنموذج المحذوف. يمكن أن تعمل هنا أيضًا علاقة بدون هدف محدد.
• حذف العلاقات
• حذف التوأم

أشياء لا يمكنك فعلها:

• تحرير العلاقات الصادرة (كما في، العلاقات من هذا التوأم إلى التوائم الأخرى)
• تحرير الخصائص

بعد الحذف: إعادة تحميل نموذج

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

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

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

تحويل نماذج v2 إلى v3

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

1. تحديث السياق. الميزة الرئيسية التي تحدد النموذج على أنه v2 أو v3 هي الحقل على @context الواجهة. لتحويل نموذج من v2 إلى v3، قم بتغيير dtmi:dtdl:context;2 قيمة السياق إلى dtmi:dtdl:context;3. بالنسبة للعديد من النماذج، سيكون هذا التغيير المطلوب الوحيد.
   1. القيمة في الإصدار 2: "@context": "dtmi:dtdl:context;2"
   2. القيمة في v3: "@context": "dtmi:dtdl:context;3".
2. إذا لزم الأمر، قم بتحديث الأنواع الدلالية. في DTDL v2، يتم دعم الأنواع الدلالية في الأصل. في DTDL v3، يتم تضمينها مع ملحق ميزة النماذج الكمية. لذلك، إذا كان نموذج v2 الخاص بك يستخدم الأنواع الدلالية، فستحتاج إلى إضافة ملحق الميزة عند تحويل النموذج إلى v3. للقيام بذلك، قم أولا بتغيير الحقل على @context الواجهة من قيمة واحدة إلى صفيف من القيم، ثم أضف القيمة dtmi:dtdl:extension:quantitativeTypes;1.
   1. القيمة في الإصدار 2: "@context": "dtmi:dtdl:context;2"
   2. القيمة في الإصدار 3: "@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1"]
3. إذا لزم الأمر، ففكر في حدود الحجم. V2 وv3 لها حدود حجم مختلفة، لذلك إذا كانت واجهتك كبيرة جدا، فقد تحتاج إلى مراجعة الحدود في الاختلافات بين DTDL v2 وv3.

بعد هذه التغييرات، تم تحويل نموذج DTDL v2 سابق إلى نموذج DTDL v3.

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

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

تعرف على كيفية إنشاء التوائم الرقمية وإدارتها استنادا إلى نماذجك:

• إدارة التوائم الرقمية