مشاركة عبر

البرنامج التعليمي: توزيع Azure Digital Twins Preview وتكوين رسم بياني مكاني

  • مقالة

هام

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

لعرض وثائق الخدمة الجديدة، تفضل بزيارة وثائق Azure Digital Twins النشطة.

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

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

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

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

في البرنامج التعليمي الأول من هذه السلسلة، ستتعلم كيفية:

  • توزيع Digital Twins.
  • امنح أذونات لتطبيقك.
  • تعديل نموذج تطبيق Digital Twins.
  • توفير المبنى الخاص بك.

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

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

  • اشتراك Azure. إذا لم يكن لديك حساب Azure، فقم بإنشاء حساب مجاني.

  • The .NET Core SDK. تتم كتابة نماذج Azure Digital Twins المستخدمة في هذه البرامج التعليمية بلغة C#. تأكد من تثبيت .NET Core SDK الإصدار 2.1.403 أو أحدث على جهاز التطوير الخاص بك لإنشاء العينة وتشغيلها. تحقق من تثبيت الإصدار الصحيح على جهازك عن طريق التشغيل dotnet --version في نافذة الأوامر.

  • Visual Studio Code لاستكشاف نموذج التعليمات البرمجية.

توزيع Digital Twins

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

  1. تسجيل الدخول إلى ⁧⁩مدخل Microsoft Azure⁧⁩.

  2. حدد الشريط الجانبي الرئيسي، ثم + إنشاء مورد.

    قم بتوسيع الشريط الجانبي للمنزل، ثم حدد + Create a resource

  3. ابحث عن Digital Twins، وحدد Digital Twins.

    تحديدات لإنشاء مثيل Digital Twins جديد

    بدلا من ذلك، حدد إنترنت الأشياء، وحدد Digital Twins (معاينة).

  4. حدد Create لبدء عملية التوزيع.

    إنشاء وتأكيد توزيع المورد

  5. في جزء Digital Twins ، أدخل المعلومات التالية:

    • اسم المورد: أنشئ اسما فريدا لمثيل Digital Twins الخاص بك.

    • الاشتراك: اختر الاشتراك الذي تريد استخدامه لإنشاء مثيل Digital Twins هذا.

    • مجموعة الموارد: حدد أو أنشئ مجموعة موارد لمثيل Digital Twins.

    • الموقع: حدد أقرب موقع إلى أجهزتك.

      جزء Digital Twins مع المعلومات المدخلة

  6. راجع معلومات Digital Twins، ثم حدد Create. قد يستغرق إنشاء مثيل Digital Twins بضع دقائق. يمكنك مراقبة التقدم في جزء الإعلامات.

  7. افتح جزء Overview لمثيل Digital Twins. لاحظ الارتباط ضمن Management API. تم تنسيق عنوان URL لواجهة برمجة تطبيقات الإدارة على النحو التالي:

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

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

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/

    سيستخدم تطبيقك عنوان URL المعدل كعنون URL أساسي للوصول إلى المثيل الخاص بك. انسخ عنوان URL المعدل هذا إلى ملف مؤقت. ستحتاج إلى هذا في القسم التالي.

    نظرة عامة على واجهة برمجة تطبيقات الإدارة

منح أذونات لتطبيقك

يستخدم Digital Twins Azure Active Directory (Azure AD) للتحكم في الوصول للقراءة/الكتابة إلى الخدمة. يجب تسجيل أي تطبيق يحتاج إلى الاتصال بمثيل Digital Twins الخاص بك مع Azure AD. توضح الخطوات الواردة في هذا القسم كيفية تسجيل نموذج التطبيق.

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

ملاحظة

يوفر هذا القسم إرشادات لتسجيل تطبيق Azure AD.

  1. في مدخل Microsoft Azure، افتح Azure Active Directory من القائمة اليسرى القابلة للتوسيع، ثم افتح جزء App registrations .

    حدد جزء Azure Active Directory

  2. حدد الزر + New registration .

    حدد زر تسجيل جديد

  3. أدخل اسما مألوفا لتسجيل هذا التطبيق في مربع الاسم .

    1. ضمن قسم Redirect URI (اختياري)، أدخل https://microsoft.com في مربع النص.

    2. تحقق من الحسابات والمستأجرين المدعومين من قبل تطبيق Azure Active Directory.

    3. اختر ⁧تسجيل⁧.

    إنشاء جزء

  4. تحدد شفرة المصادقة إعدادات تكوين المصادقة المهمة.

    1. أضف Redirect URIs وقم بتكوين Access Tokens عن طريق تحديد + Add a platform.

    2. حدد نعم لتحديد أن التطبيق عميل عام.

    3. تحقق من الحسابات والمستأجرين المدعومين من قبل تطبيق Azure Active Directory.

    إعداد تكوين العميل العام

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

    1. يجب أن تتطابق عناوين URI لإعادة التوجيه مع العنوان الذي يوفره طلب المصادقة:

      • بالنسبة للتطبيقات المستضافة في بيئة تطوير محلية، حدد العميل العام (الجوال & سطح المكتب). تأكد من تعيين العميل العام إلى نعم.
      • بالنسبة Single-Page التطبيقات المستضافة على Azure App Service، حدد Web.

    2. حدد ما إذا كان عنوان URL لتسجيل الخروج مناسبا أم لا.

    3. قم بتمكين تدفق المنح الضمني عن طريق التحقق من رموز الوصول المميزة أو الرموز المميزة للمعرف.

    تكوين عناوين URL لإعادة التوجيه

    انقر فوق تكوين، ثم حفظ.

  6. افتح جزء Overview لتطبيقك المسجل، وانسخ قيم الكيانات التالية إلى ملف مؤقت. ستستخدم هذه القيم لتكوين نموذج التطبيق الخاص بك في الأقسام التالية.

    • مُعرَّف التطبيق (العميل)
    • معرف الدليل (المستأجر)

    معرف تطبيق Azure Active Directory

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

    1. Azure Digital Twins. حدد واجهة برمجة تطبيقات Azure Digital Twins .

      البحث عن واجهة برمجة التطبيقات أو Azure Digital Twins

    2. بدلا من ذلك، ابحث Azure Smart Spaces Serviceعن . حدد واجهة برمجة تطبيقات Azure Smart Spaces Service .

      البحث عن واجهة برمجة التطبيقات ل Azure Smart Spaces

    هام

    يعتمد اسم واجهة برمجة التطبيقات Azure AD والمعرف الذي سيظهر على المستأجر الخاص بك:

    • يجب أن يبحث اختبار حسابات المستأجر والعملاء عن Azure Digital Twins.
    • يجب أن تبحث Azure Smart Spaces Serviceحسابات Microsoft الأخرى عن .

  8. ستظهر أي من واجهة برمجة التطبيقات ك Azure Digital Twins في نفس جزء طلب أذونات واجهة برمجة التطبيقات بمجرد تحديدها. حدد الخيار المنسدلة قراءة ، ثم حدد خانة الاختيار قراءة.كتابة . حدد الزر ⁧⁩Add permissions⁧⁩.

    إضافة أذونات واجهة برمجة التطبيقات

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

    الموافقة مسؤول

    تحقق من ظهور Azure Digital Twins .

تكوين نموذج Digital Twins

يرشدك هذا القسم عبر تطبيق Azure Digital Twins الذي يتصل بواجهات برمجة تطبيقات Digital Twins REST.

تنزيل العينة

إذا كان لديك بالفعل العينات التي تم تنزيلها لبدء التشغيل السريع للعثور على الغرف المتوفرة، يمكنك تخطي هذه الخطوات.

  1. قم بتنزيل نماذج Digital Twins .NET.
  2. استخراج محتويات المجلد المضغوط على جهازك.

استكشاف العينة

في مجلد العينة المستخرجة، افتح الملف digital-twins-samples-csharp\digital-twins-samples.code-workspace في Visual Studio Code. يحتوي على مشروعين:

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

    لاستكشاف النموذج لفهم كيفية اتصاله بمثيل Digital Twins الخاص بك، يمكنك البدء بمجلد src\actions . تنفذ الملفات الموجودة في هذا المجلد الأوامر التي ستستخدمها في هذه البرامج التعليمية:

    • يوضح ملف provisionSample.cs كيفية توفير الرسم البياني المكاني الخاص بك.
    • يحصل ملف getSpaces.cs على معلومات حول المسافات المتوفرة.
    • يحصل ملف getAvailableAndFreshSpaces.cs على نتائج دالة مخصصة تسمى دالة معرفة من قبل المستخدم.
    • ينشئ ملف createEndpoints.cs نقاط نهاية للتفاعل مع الخدمات الأخرى.

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

تكوين نموذج التزويد

  1. افتح نافذة أوامر وانتقل إلى العينة التي تم تنزيلها. تشغيل الأمر التالي:

    cd occupancy-quickstart/src

  2. استعادة التبعيات إلى نموذج المشروع عن طريق تشغيل هذا الأمر:

    dotnet restore

  3. في Visual Studio Code، افتح ملف appSettings.json في مشروع التشغيل السريع للشغل . قم بتحديث القيم التالية:

    • ClientId: أدخل معرف التطبيق لتسجيل تطبيق Azure AD. لقد لاحظت هذا المعرف في القسم حيث قمت بتعيين أذونات التطبيق.
    • المستأجر: أدخل معرف الدليل لمستأجر Azure AD. كما لاحظت هذا المعرف في القسم حيث قمت بتعيين أذونات التطبيق.
    • BaseUrl: أدخل عنوان URL لمثيل Digital Twins الخاص بك. للحصول على عنوان URL هذا، استبدل العناصر النائبة في عنوان URL هذا بقيم للمثيل الخاص بك: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. يمكنك أيضا الحصول على عنوان URL هذا عن طريق تعديل عنوان URL لواجهة برمجة تطبيقات الإدارة من قسم التوزيع. استبدل swagger/ ب api/v1.0/.

  4. راجع قائمة ميزات Digital Twins التي يمكنك استكشافها باستخدام العينة. تشغيل الأمر التالي:

    dotnet run

فهم عملية التزويد

يوضح هذا القسم كيف توفر العينة رسما بيانيا مكانيا للمبنى.

في Visual Studio Code، استعرض للوصول إلى المجلد occupancy-quickstart\src\actions وافتح الملف provisionSample.cs. لاحظ الدالة التالية:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

تستخدم هذه الدالة provisionSample.yaml في نفس المجلد. افتح هذا الملف، ولاحظ التسلسل الهرمي لمبنى مكتب: المكانوالطابقوالمنطقةوالغرف. يمكن أن تحتوي أي من هذه المساحات المادية على أجهزة وأجهزة استشعار. يحتوي كل إدخال على معرف typeمسبقا — على سبيل المثال، Floor, Room.

يعرض نموذج ملف yaml رسما بيانيا مكانيا يستخدم Default نموذج عنصر Digital Twins. يوفر هذا النموذج أسماء عامة لمعظم الأنواع. الأسماء العامة كافية للمبنى. ومن الأمثلة على ذلك درجة الحرارة ل SensorDataType، وخريطة SpaceBlobType. مثال على نوع المساحة هو الغرفة ذات الأنواع الفرعية FocusRoom و ConferenceRoom وما إلى ذلك.

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

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

تعديل نموذج الرسم البياني المكاني

يحتوي ملف provisionSample.yaml على العقد التالية:

  • الموارد: resources تنشئ العقدة مورد Azure IoT Hub للاتصال بالأجهزة في الإعداد الخاص بك. يمكن لمركز IoT في العقدة الجذر للرسم البياني الخاص بك الاتصال بجميع الأجهزة وأجهزة الاستشعار في الرسم البياني الخاص بك.

  • المسافات: في نموذج عنصر Digital Twins، spaces تمثل المواقع الفعلية. تحتوي Typeكل مساحة على - على سبيل المثال، المنطقة أو المكان أو العميل - ودود Name. يمكن أن تنتمي المسافات إلى مسافات أخرى، مما يؤدي إلى إنشاء بنية هرمية. يحتوي ملف provisionSample.yaml على رسم بياني مكاني لمبنى وهمي. لاحظ التداخل المنطقي للمسافات من النوع Floor داخل Venue، Area في الكلمة، والعقد Room في منطقة.

  • الأجهزة: يمكن أن تحتوي المسافات على devices، وهي كيانات فعلية أو ظاهرية تدير عددا من أجهزة الاستشعار. على سبيل المثال، قد يكون الجهاز هاتف مستخدم أو حاوية مستشعر Raspberry Pi أو بوابة. في المبنى التخيلي في العينة الخاصة بك، لاحظ كيف تحتوي الغرفة المسماة "غرفة التركيز" على جهاز Raspberry Pi 3 A1 . يتم تحديد كل عقدة جهاز بواسطة فريد hardwareId، والذي يتم ترميزه في العينة. لتكوين هذه العينة لإنتاج فعلي، استبدلها بقيم من الإعداد الخاص بك.

  • أدوات الاستشعار: يمكن أن يحتوي الجهاز على عدة sensors. يمكنهم اكتشاف وتسجيل التغييرات المادية مثل درجة الحرارة والحركة ومستوى البطارية. يتم تحديد كل عقدة أداة استشعار بشكل فريد بواسطة hardwareId، مشفرة هنا. بالنسبة لتطبيق فعلي، استبدلها باستخدام المعرفات الفريدة لأجهزة الاستشعار في الإعداد الخاص بك. يحتوي ملف provisionSample.yaml على جهازي استشعار لتسجيل Motion و CarbonDioxide. أضف مستشعرا آخر لتسجيل درجة الحرارة، عن طريق إضافة الأسطر التالية، أسفل خطوط مستشعر CarbonDioxide. يتم توفيرها في provisionSample.yaml كخطوط معلق بها. يمكنك إلغاء التعليق عليها عن طريق إزالة # الحرف في مقدمة كل سطر.

            - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE

    ملاحظة

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

احفظ الملف provisionSample.yaml وأغلقه. في البرنامج التعليمي التالي، ستضيف المزيد من المعلومات إلى هذا الملف، ثم توفر بناء عينة Azure Digital Twins.

تلميح

يمكنك عرض الرسم البياني المكاني وتعديله باستخدام Azure Digital Twins Graph Viewer.

تنظيف الموارد

إذا كنت ترغب في التوقف عن استكشاف Azure Digital Twins في هذه المرحلة، فلا تتردد في حذف الموارد التي تم إنشاؤها في هذا البرنامج التعليمي:

  1. من القائمة اليسرى في مدخل Microsoft Azure، حدد All resources، وحدد مجموعة موارد Digital Twins، وحدد Delete.

    تلميح

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

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

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

لمعرفة كيفية تنفيذ منطق مخصص لمراقبة الظروف في بناء العينة، انتقل إلى البرنامج التعليمي التالي في السلسلة:

البرنامج التعليمي: توفير ظروف العمل الخاصة بك للبناء ومراقبة