ابدأ باستخدام هوية وحدة IoT Hub والوحدة المزدوجة (.NET)

مقالة
10/01/2024

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

إشعار

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

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

CreateIdentities: يُنشئ هوية جهاز وهوية الوحدة ومفتاح أمان مرتبط لتوصيل جهازك الخاص وعملاء الوحدة.
UpdateModuleTwinReportedProperties: يرسل خصائص وحدة مزدوجة مُحدَّثة والخصائص المُبلَّغ عنها إلى مركز IoT خاصتك.

إشعار

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

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

Visual Studio.
مركز IoT في اشتِراك Azure الخاص بك. إذا لم تكن لديك مركز بعد، فإنه يمكنك اتباع الخطوات الواردة في إنشاء مركز IoT.

مصادقة الوحدة النمطية

يمكنك استخدام مفاتيح متماثلة أو شهادات X.509 لمصادقة هويات الوحدة النمطية. لمصادقة شهادة X.509، يجب أن يكون لشهادة الوحدة النمطية اسمها الشائع (CN) منسقا مثل CN=<deviceid>/<moduleid>. على سبيل المثال:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

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

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

للحصول على سلسلة اتصال IoT Hub لنهج RegistryReadWrite، اتبع الخطوات التالية:

في مدخل Microsoft Azure، حدد Resource groups. حدد مجموعة الموارد حيث يوجد المركز الخاص بك، ثم حدد المركز الخاص بك من قائمة الموارد.
في الجزء الأيسر من مركز IoT، قم بتحديد Shared access policies.
من قائمة النهج، حدد نهج registryReadWrite.
انسخ سلسلة الاتصال الأساسية واحفظ القيمة.

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

هام

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

قم بإنشاء هوية وحدة

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

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

افتح Visual Studio وحدد "أنشئ مشروعًا جديدًا ".
في Create a new project، حدد Console App (.NET Framework).
حدد Next لفتح Configure your new project. أطلق اسم CreateIdentitiesعلى المشروع، ثم حدد التالي.
احتفظ بخيار .NET Framework الافتراضي وحدد إنشاء لإنشاء مشروعك.
في Visual Studio، افتح Tools>NuGet Package Manager>إدارة حزم NuGet للحلول. حدد علامة التبويب Browse.
ابحث عن Microsoft.Azure.Devices. حدده ثم حدد Install.
إضافة العبارات التالية using في الجزء العلوي من الملف Program.cs:
```
using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;
```
إضافة الحقول التالية إلى فئة البرنامج. استبدل قيمة العنصر النائب بسلسلة اتصال IoT Hub للمركز الذي أنشأته في القسم السابق.
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

أضف التعليمة البرمجية التالية إلى فئة الرئيسي.

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

أضف الطرق التالية إلى فئة البرنامج :
```
private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}
```
تنشئ الطريقة AddDeviceAsync هوية جهاز بالمعرف myFirstDevice. إذا كان معرف الجهاز موجوداً بالفعل في سجل الهوية، يقوم التعليمة البرمجية ببساطة باسترداد معلومات الجهاز الموجودة. ثم يعرض التطبيق المفتاح الأساسي لتلك الهوية. يمكنك استخدام هذا المفتاح في تطبيق الجهاز الذي تمت محاكاته للاتصال بالمركز.

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

هام

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

إشعار

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

قم بتحديث الوحدة النمطية المزدوجة باستخدام .NET device SDK

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

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

هام

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

في Visual Studio، أضف مشروعاً جديداً إلى الحل الخاص بك عن طريق تحديد File>New>Project. في إنشاء مشروع جديد، حدد Console App (.NET Framework)، وحدد Next.
في تكوين مشروعك الجديد، أطلق اسم UpdateModuleTwinReportedProperties على المشروع ثم حدد التالي.
احتفظ بخيار .NET Framework الافتراضي وحدد إنشاء لإنشاء مشروعك.
في Visual Studio، افتح Tools>NuGet Package Manager>إدارة حزم NuGet للحلول. حدد علامة التبويب Browse.
ابحث عن وحدد Microsoft.Azure.Devices.Client، ثم حدد Install.

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

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

إضافة الحقول التالية إلى فئة البرنامج. استبدل قيمة العنصر النائب بسلسلة اتصال الوحدة النمطية.

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

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

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

أضف الأسطر التالية إلى الطريقة الرئيسية :

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

أنت الآن تعرف كيفية استرداد الوحدة النمطية المزدوجة وتحديث الخصائص المبلغ عنها باستخدام بروتوكول AMQP.

اختيارياً، يمكنك إضافة هذه العبارات إلى الطريقة الرئيسية لإرسال حدث إلى IoT Hub من الوحدة النمطية الخاصة بك. ضع هذه الخطوط أسفل الكتلة try catch.
```
Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");
```

قم بتشغيل التطبيقات

يمكنك الآن تشغيل التطبيقات.

في Visual Studio، في مستكشف الحلول، انقر بزر الماوس الأيمن فوق الحل، ثم حدد Set StartUp projects.
ضمن Common Properties، حدد Startup Project.
حدد Multiple startup projects، ثم حدد Start كإجراء للتطبيقات، وOK لقبول التغييرات.
اضغط على F5 لبدء التطبيقات.

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

لمتابعة بدء استخدام IoT Hub واستكشاف سيناريوهات إنترنت الأشياء الأخرى، راجع:

مشاركة عبر

ابدأ باستخدام هوية وحدة IoT Hub والوحدة المزدوجة (.NET)

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

مصادقة الوحدة النمطية

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

قم بإنشاء هوية وحدة

قم بتحديث الوحدة النمطية المزدوجة باستخدام .NET device SDK

قم بتشغيل التطبيقات

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

الملاحظات

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