بدء استخدام الجهاز التوائم (.NET)

  • مقالة

توائم الجهاز عبارة عن مستندات JSON تُخزِّن معلومات حالة الجهاز، بما في ذلك بيانات التعريف والتكوينات والحالات. يحتفظ IoT Hub بتوأم جهاز لكل جهاز يتصل به.

إشعار

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

استخدم توائم الجهاز من أجل ما يلي:

  • خزّن بيانات التعريف للجهاز من النهاية الخلفية للحل الخاص بك.

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

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

  • الاستعلام عن بيانات التعريف للجهاز، أو التكوين، أو الحالة.

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

تخزن مراكز IoT توائم الجهاز، والتي تحتوي على العناصر التالية:

  • العلامات. يمكن الوصول إلى بيانات التعريف للجهاز فقط من خلال النهاية الخلفية للحل.

  • الخصائص المرغوبة. عناصر JSON قابلة للتعديل من خلال النهاية الخلفية للحل ويمكن ملاحظتها بواسطة تطبيق الجهاز.

  • الخصائص المبلغ عنها. عناصر JSON قابلة للتعديل من خلال تطبيق الجهاز ويمكن قراءتها بواسطة النهاية الخلفية للحل.

لا يمكن أن تحتوي العلامات والخصائص على صفائف، ولكن يمكن أن تحتوي على كائنات متداخلة.

يوضح الرسم التوضيحي التالي تنظيم توأم الجهاز:

لقطة شاشة لمخطط مفهوم توأم الجهاز.

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

توضح لك هذه المقالة كيفية:

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

  • استعلم عن الأجهزة من تطبيقك الخلفي باستخدام عوامل تصفية على العلامات والخصائص التي تم إنشاؤها مسبقًا.

في هذه المقالة، يمكنك إنشاء تطبيقي وحدة تحكم .NET:

  • AddTagsAndQuery: تطبيق للجهة الخلفية يضيف علامات واستعلامات توائم الجهاز.

  • ReportConnectivity: تطبيق جهاز محاكاة يتصل بمركز IoT ويبلغ عن حالة الاتصال.

إشعار

راجع Azure IoT SDKs لمزيد من المعلومات حول أدوات SDK المتوفرة لإنشاء كل من الجهاز والتطبيقات الخلفية.

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

  • Visual Studio.

  • IoT Hub. أنشئ واحدا باستخدام CLI أو مدخل Microsoft Azure.

  • جهاز مسجل. سجَل واحدًا في مدخل Azure.

  • تأكد من أن المنفذ 8883 مفتوح في جدار الحماية. يستخدم نموذج الجهاز في هذه المقالة بروتوكول MQTT، الذي يتصل عبر المنفذ 8883. قد يُحظر هذا المنفذ في بعض بيئات الشبكات التعليمية، وشبكات الشركات. لمزيد من المعلومات وطرق التغلب على هذه المشكلة، راجع الاتصال بمركز IoT (MQTT).

احصل على سلسلة اتصال IoT hub

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

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

  1. في مدخل Microsoft Azure، حدد Resource groups. حدد مجموعة الموارد حيث يوجد المركز الخاص بك، ثم حدد المركز الخاص بك من قائمة الموارد.

  2. في الجزء الأيسر من مركز IoT، قم بتحديد Shared access policies.

  3. من القائمة أعلى قائمة النهج، حدّد إضافة نهج الوصول المشترك.

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

    لقطة شاشة توضح كيفية إضافة نهج وصول مشترك جديد.

  5. حدد النهج الخاص بك الجديدة من قائمة النُهج.

  6. حدد أيقونة النسخ لسلسلة الاتصال الأساسية واحفظ القيمة.

    لقطة شاشة توضح كيفية استرداد سلسلة الاتصال.

للمزيد من المعلومات حول نهج الوصول المشترك لـIoT Hub والأذونات، راجع التحكم في الوصول والأذونات.

إنشاء تطبيق جهاز يقوم بتحديث الخصائص المبلغ عنها

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

  1. افتح Visual Studio وحدد إنشاء مشروع جديد.

  2. اختر تطبيق وحدة التحكم (.NET Framework)، ثم حدد التالي.

  3. في تكوين مشروعك الجديد، قم بتسمية المشروع ReportConnectivity، ثم حدد التالي.

  4. في مستكشف الحلول، انقر بزر الماوس الأيمن فوق مشروع ReportConnectivity، ثم حدد Manage NuGet Packages.

  5. احتفظ بالإصدار الافتراضي من .NET Framework، ثم حدد إنشاء لإنشاء المشروع.

  6. حدد Browse وابحث عن واختر Microsoft.Azure.Devices.Client. حدد تثبيت.

    تقوم هذه الخطوة بتنزيل وتثبيت وإضافة مرجع إلى حزمة NuGetعدة تطوير البرامج لجهاز Azure IoT وتبعياتها.

  7. إضافة العبارات التالية using في الجزء العلوي من الملف Program.cs:

    using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

  8. إضافة الحقول التالية إلى فئة البرنامج. استبدل {device connection string} بسلسلة اتصال الجهاز التي رأيتها عند تسجيل جهاز في مركز IoT:

    static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

  9. إضافة الطريقة التالية إلى فئة البرنامج:

    public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

    يكشف عنصر العميل عن جميع الطرق التي تتطلبها للتفاعل مع توائم الجهاز من الجهاز. تعمل التعليمة البرمجية الموضحة أعلاه على تهيئة العنصر Client، ثم استرداد الجهاز المزدوج لـ myDeviceId.

  10. إضافة الطريقة التالية إلى فئة البرنامج:

    public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

    يقوم التعليمة البرمجية أعلاه بتحديث الخاصية المبلغ عنها لـ myDeviceId بمعلومات الاتصال.

  11. وأخيراً، أضف الأسطر التالية إلى الطريقةالرئيسية:

    try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

  12. في Solution Explorer، انقر بزر الماوس الأيمن فوق الحل الخاص بك، وحدد Set StartUp Projects.

  13. في Common Properties>Startup Project، حدد Multiple startup projects. بالنسبة إلى ReportConnectivity، حدد Start باعتباره Action. حدد موافق لحفظ تغييراتك.

  14. شغّل هذا التطبيق بالنقر بزر الماوس الأيمن على مشروع ReportConnectivity وتحديد Debug، ثم Start new instance. من المفترض أن ترى التطبيق يحصل على المعلومات المزدوجة، ثم يرسل الاتصال باعتباره خاصية تم الإبلاغ عنها.

    قم بتشغيل تطبيق الجهاز للإبلاغ عن الاتصال

    بعد أن أبلغ الجهاز عن معلومات الاتصال الخاصة به، يجب أن تظهر في كلا الاستعلامين.

  15. انقر بزر الماوس الأيمن فوق مشروع AddTagsAndQuery وحدد Debug>Start new instance لتشغيل الاستعلامات مرة أخرى. هذه المرة، يجب أن يظهر myDeviceId في كل نتائج طلب البحث.

    تم الإبلاغ عن اتصال الجهاز بنجاح

إنشاء تطبيق خدمة يقوم بتحديث الخصائص المطلوبة والاستعلامات المزدوجة

في هذا القسم، تقوم بإنشاء تطبيق NET console. باستخدام #C، والذي يضيف بيانات التعريف للموقع إلى الجهاز المزدوج المرتبط بـ myDeviceId. يستعلم التطبيق عن مركز IoT للأجهزة الموجودة في الولايات المتحدة، ثم عن الأجهزة التي تبلغ عن اتصال شبكة خلوية.

  1. في Visual Studio، حدد ملف > جديد > مشروع. في Create a new project، حدد Console App (.NET Framework)، ثم حدد Next.

  2. في تكوين مشروعك الجديد، قم بتسمية المشروع AddTagsAndQuery، ثم حدد التالي.

    لقطة شاشة توضح كيفية إنشاء مشروع جديد في Visual Studio.

  3. اقبل الإصدار الافتراضي من .NET Framework، ثم حدد إنشاء لإنشاء المشروع.

  4. في مستكشف الحلول، انقر بزر الماوس الأيمن فوق مشروع AddTagsAndQuery، ثم حدد Manage NuGet Packages.

  5. حدد Browse وابحث عن Microsoft.Azure.Devicesوحدده. حدد تثبيت.

    نافذة NuGet Package Manager

    تقوم هذه الخطوة بتنزيل وتثبيت وإضافة مرجع إلى حزمة NuGet Azure IoT service SDK وتبعياتها.

  6. إضافة العبارات التالية using في الجزء العلوي من الملف Program.cs:

    using Microsoft.Azure.Devices;

  7. إضافة الحقول التالية إلى فئة البرنامج. استبدل {iot hub connection string} بسلسلة اتصال IoT Hub التي نسختها في الحصول على سلسلة اتصال IoT hub.

    static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";

  8. إضافة الطريقة التالية إلى فئة البرنامج:

    public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

    var query = registryManager.CreateQuery(
      "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
    var twinsInRedmond43 = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43: {0}", 
      string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}

    تعرض فئة RegistryManager جميع الطرق المطلوبة للتفاعل مع توائم الجهاز من الخدمة. يهيئ التعليمة البرمجية السابق أولاً عنصر registryManager، ثم يسترد توأم الجهاز لـ myDeviceId، وأخيراً يقوم بتحديث علاماته بمعلومات الموقع المطلوبة.

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

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

  9. وأخيراً، أضف الأسطر التالية إلى الطريقةالرئيسية:

    registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

  10. قم بتشغيل هذا التطبيق بالنقر بزر الماوس الأيمن على مشروع AddTagsAndQuery وتحديد Debug، متبوعاً بـ Start new instance. من المفترض أن ترى جهازًا واحدًا في نتائج الاستعلام الذي يبحث عن جميع الأجهزة الموجودة في Redmond43 ولا شيء للاستعلام الذي يقيد النتائج على الأجهزة التي تستخدم شبكة خلوية.

    نتائج الاستعلام في النافذة

في هذه المقالة، ستتمكن من:

  • إضافة بيانات تعريف الجهاز كعلامات من تطبيق خلفي
  • الإبلاغ عن معلومات اتصال الجهاز في توأم الجهاز
  • الاستعلام عن معلومات توأم الجهاز باستخدام لغة استعلام مركز IoT تشبه SQL

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

‏‫تعّرف على كيفية: