البدء مع توائم الأجهزة

• يتطلب Visual Studio

نظرة عامة

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

إنشاء تطبيق جهاز

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

يصف هذا القسم كيفية استخدام التعليمات البرمجية لتطبيق الجهاز من أجل:

• استرداد توأم جهاز وفحص الخصائص المبلغ عنها
• تحديث خصائص الجهاز المزدوج المبلغ عنها
• إنشاء معالج رد اتصال لتحديث الخاصية المطلوبة

حزمة NuGet للجهاز المطلوب

تتطلب تطبيقات عميل الجهاز المكتوبة بلغة C# حزمة Microsoft.Azure.Devices.Client NuGet.

أضف هذه using العبارة لاستخدام مكتبة الجهاز.

using Microsoft.Azure.Devices.Client;

توصيل جهاز بـ IoT Hub

يمكن مصادقة تطبيق الجهاز باستخدام IoT Hub باستخدام الطرق التالية:

• مفتاح الوصول المشترك
• شهادة X.509

المصادقة باستخدام مفتاح وصول مشترك

تعرض فئة DeviceClient جميع الطرق المطلوبة للتفاعل مع توائم الجهاز من الجهاز.

الاتصال بالجهاز باستخدام أسلوب CreateFromConnectionString جنبا إلى جنب مع سلسلة الاتصال الجهاز وبروتوكول نقل الاتصال.

CreateFromConnectionString تدعم معلمة بروتوكول النقل TransportType بروتوكولات النقل التالية:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only

Http1 البروتوكول غير مدعوم للتحديثات المزدوجة للجهاز.

يتصل هذا المثال بجهاز باستخدام Mqtt بروتوكول النقل.

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

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

المصادقة باستخدام شهادة X.509

لتوصيل جهاز ب IoT Hub باستخدام شهادة X.509:

1. استخدم DeviceAuthenticationWithX509Certificate لإنشاء كائن يحتوي على معلومات الجهاز والشهادة. DeviceAuthenticationWithX509Certificate يتم تمرير كمعلمة ثانية إلى DeviceClient.Create (الخطوة 2).

2. استخدم DeviceClient.Create لتوصيل الجهاز ب IoT Hub باستخدام شهادة X.509.

في هذا المثال، يتم ملء معلومات الجهاز والشهادة في authDeviceAuthenticationWithX509Certificate الكائن الذي يتم تمريره إلى DeviceClient.Create.

يوضح هذا المثال قيم معلمات إدخال الشهادة كمتغيرات محلية للوضوح. في نظام الإنتاج، قم بتخزين معلمات الإدخال الحساسة في متغيرات البيئة أو موقع تخزين آخر أكثر أمانا. على سبيل المثال، استخدم Environment.GetEnvironmentVariable("HOSTNAME") لقراءة متغير بيئة اسم المضيف.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

• مصادقة الهويات باستخدام شهادات X.509
• البرنامج التعليمي: إنشاء الشهادات وتحميلها للاختبار

نماذج التعليمات البرمجية

للحصول على نماذج العمل لمصادقة شهادة X.509 للجهاز، راجع:

• الاتصال بشهادة X.509
• DeviceClientX509AuthenticationE2ETests
• مشروع موجه - توفير أجهزة IoT بشكل آمن وعلى نطاق واسع باستخدام خدمة توفير جهاز IoT Hub

استرداد توأم جهاز وفحص الخصائص

اتصل ب GetTwinAsync لاسترداد خصائص الجهاز المزدوج الحالية. هناك العديد من خصائص الكائن المزدوج التي يمكنك استخدامها للوصول إلى مناطق معينة من Twin بيانات JSON بما في ذلك Propertiesو TagsStatusو وVersion.

يسترد هذا المثال خصائص الجهاز المزدوج ويطبع القيم المزدوجة بتنسيق JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

تحديث خصائص الجهاز المزدوج المبلغ عنها

لتحديث خاصية مزدوجة تم الإبلاغ عنها:

1. إنشاء كائن TwinCollection لتحديث الخاصية التي تم الإبلاغ عنها
2. تحديث خاصية واحدة أو أكثر تم الإبلاغ عنها داخل TwinCollection الكائن
3. استخدام UpdateReportedPropertiesAsync لدفع تغييرات الخصائص المبلغ عنها إلى خدمة مركز IoT

على سبيل المثال:

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

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

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

على سبيل المثال، يقوم هذا الاستدعاء بإعداد النظام لإعلام أسلوب يسمىOnDesiredPropertyChangedAsync كلما تم تغيير خاصية مطلوبة.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

يتم تمرير الخصائص المزدوجة إلى أسلوب رد الاتصال ك TwinCollection ويمكن فحصها كهياكل KeyValuePair .

يتلقى هذا المثال تحديثات الخاصية المطلوبة ك TwinCollection، ثم يتكرر ويطبع KeyValuePair تحديثات المجموعة. بعد التكرار الحلقي عبر KeyValuePair المجموعة، تستدعي UpdateReportedPropertiesAsync التعليمات البرمجية لتحديث الخاصية التي DateTimeLastDesiredPropertyChangeReceived تم الإبلاغ عنها للحفاظ على آخر وقت محدث محدث.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

نموذج جهاز SDK

يوفر Azure IoT SDK ل .NET عينة عمل لتطبيق جهاز يعالج المهام المزدوجة للجهاز. لمزيد من المعلومات، راجع TwinSample.

إنشاء تطبيق خلفية

يتصل تطبيق الواجهة الخلفية بجهاز من خلال IoT Hub ويمكنه قراءة الخصائص التي تم الإبلاغ عنها والخصائص المطلوبة للجهاز وكتابة الخصائص المطلوبة للجهاز وتشغيل استعلامات الجهاز.

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

• قراءة وتحديث الحقول المزدوجة للجهاز
• إنشاء استعلام مزدوج للجهاز

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

إضافة حزمة NuGet للخدمة

تتطلب تطبيقات الخدمة الخلفية حزمة Microsoft.Azure.Devices NuGet.

الاتصال بمركز IoT

يمكنك توصيل خدمة خلفية ب IoT Hub باستخدام الطرق التالية:

• نهج الوصول المشترك
• Microsoft Entra

الاتصال باستخدام نهج وصول مشترك

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

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

الاتصال باستخدام Microsoft Entra

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

تكوين تطبيق Microsoft Entra

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

• سر العميل
• شهادة
• بيانات اعتماد الهوية الموحدة

قد تتطلب تطبيقات Microsoft Entra أذونات دور محددة اعتمادا على العمليات التي يتم تنفيذها. على سبيل المثال، مطلوب IoT Hub Twin Contributor لتمكين الوصول للقراءة والكتابة إلى جهاز IoT Hub وتوائم الوحدة النمطية. لمزيد من المعلومات، راجع إدارة الوصول إلى IoT Hub باستخدام تعيين دور Azure RBAC.

لمزيد من المعلومات حول إعداد تطبيق Microsoft Entra، راجع التشغيل السريع: تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft.

المصادقة باستخدام DefaultAzureCredential

أسهل طريقة لاستخدام Microsoft Entra لمصادقة تطبيق الواجهة الخلفية هي استخدام DefaultAzureCredential، ولكن يوصى باستخدام طريقة مختلفة في بيئة إنتاج بما في ذلك طريقة معينة TokenCredential أو موزعة.ChainedTokenCredential للتبسيط، يصف هذا القسم المصادقة باستخدام DefaultAzureCredential وسر العميل. لمزيد من المعلومات حول إيجابيات وسلبيات استخدام DefaultAzureCredential، راجع إرشادات الاستخدام ل DefaultAzureCredential.

DefaultAzureCredential يدعم آليات المصادقة المختلفة ويحدد نوع بيانات الاعتماد المناسب استنادا إلى البيئة التي ينفذ فيها. يحاول استخدام أنواع بيانات اعتماد متعددة بترتيب حتى يعثر على بيانات اعتماد عاملة.

يتطلب Microsoft Entra حزم NuGet هذه والعبارات المقابلة using :

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

في هذا المثال، تتم إضافة سر عميل تسجيل تطبيق Microsoft Entra ومعرف العميل ومعرف المستأجر إلى متغيرات البيئة. يتم استخدام متغيرات البيئة هذه من قبل DefaultAzureCredential لمصادقة التطبيق. نتيجة مصادقة Microsoft Entra الناجحة هي بيانات اعتماد رمز أمان يتم تمريرها إلى أسلوب اتصال IoT Hub.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

يمكن بعد ذلك تمرير TokenCredential الناتج إلى أسلوب الاتصال ب IoT Hub لأي عميل SDK يقبل بيانات اعتماد Microsoft Entra:

• JobClient
• إدارة السجل
• DigitalTwinClient
• ServiceClient

في هذا المثال، TokenCredential يتم تمرير إلى ServiceClient.Create لإنشاء كائن اتصال ServiceClient .

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

في هذا المثال، TokenCredential يتم تمرير إلى RegistryManager.Create لإنشاء كائن RegistryManager .

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Code sample

للحصول على عينة عمل من مصادقة خدمة Microsoft Entra، راجع نموذج المصادقة المستندة إلى الدور.

قراءة وتحديث الحقول المزدوجة للجهاز

يمكنك استرداد حقول الجهاز المزدوج الحالية في كائن Twin عن طريق استدعاء GetTwinAsync.

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

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

قراءة وتحديث علامات الجهاز المزدوجة

استخدم خاصية العلامات المزدوجة للجهاز لقراءة معلومات علامة الجهاز وكتابتها.

تحديث العلامات باستخدام كائن مزدوج

ينشئ هذا المثال تصحيح علامة location ، ويعينه إلى Twin الكائن باستخدام الخاصية Tags ، ثم يطبق التصحيح باستخدام UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

تحديث العلامات باستخدام سلسلة JSON

يمكنك إنشاء تطبيق تصحيح تحديث معلومات الجهاز المزدوج بتنسيق JSON. يوزع IoT Hub التصحيح ويطبقه إذا تم تنسيقه بشكل صحيح.

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

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

عرض وتحديث الخصائص المزدوجة المطلوبة

استخدم خاصية TwinProperties.Desired للجهاز لقراءة وكتابة معلومات الخاصية المطلوبة للجهاز. تحديث خصائص التوأم Desired باستخدام تصحيح بتنسيق JSON.

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

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

أساليب التحديث المزدوجة الأخرى

يمكنك أيضا تطبيق تحديثات مزدوجة باستخدام أساليب SDK هذه:

• اتصل ب ReplaceTwinAsync لاستبدال الجهاز المزدوج بأكمله.
• اتصل ب UpdateTwins2Async لتحديث قائمة التوائم التي تم إنشاؤها مسبقا داخل النظام.

إنشاء استعلام مزدوج للجهاز

يوضح هذا القسم استعلامين لجهاز مزدوج. استعلامات الجهاز المزدوج هي استعلامات تشبه SQL التي ترجع مجموعة نتائج من توائم الجهاز.

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

الاستدعاء GetNextAsTwinAsync التالي أو GetNextAsJsonAsync الأسلوب عدة مرات حسب الحاجة لاسترداد جميع النتائج المزدوجة.

• GetNextAsTwinAsync لاسترداد النتيجة التالية المصفحة كعناصر Twin .
• GetNextAsJsonAsync لاسترداد النتيجة التالية المصفحة كسلاسل JSON.

تتضمن الواجهة IQuery خاصية منطقية HasMoreResults يمكنك استخدامها للتحقق مما إذا كان هناك المزيد من النتائج المزدوجة لجلبها.

يحدد هذا الاستعلام المثال فقط توائم الجهاز للأجهزة الموجودة في مصنع Redmond43 .

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)));

عينة خدمة SDK

يوفر Azure IoT SDK ل .NET عينة عمل لتطبيق خدمة يعالج المهام المزدوجة للجهاز. لمزيد من المعلومات، راجع نموذج إدارة السجل.

• يتطلب Java SE Development Kit 8. تأكد من تحديد Java 8 ضمن الدعم طويل المدى للانتقال إلى التنزيلات ل JDK 8.

نظرة عامة

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

إنشاء تطبيق جهاز

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

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

• استرداد جهاز مزدوج وعرضه
• تحديث خصائص الجهاز المزدوج المبلغ عنها
• الاشتراك في تغييرات الخاصية المطلوبة

تعرض فئة DeviceClient جميع الطرق التي تحتاجها للتفاعل مع توائم الجهاز من الجهاز.

عبارات استيراد الجهاز

استخدم عبارات استيراد الجهاز التالية للوصول إلى Azure IoT SDK ل Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

توصيل جهاز بـ IoT Hub

يمكن مصادقة تطبيق الجهاز باستخدام IoT Hub باستخدام الطرق التالية:

• مفتاح الوصول المشترك
• شهادة X.509

المصادقة باستخدام مفتاح وصول مشترك

لتوصيل جهاز ب IoT Hub:

1. استخدم IotHubClientProtocol لاختيار بروتوكول نقل. على سبيل المثال:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. استخدم الدالة DeviceClient الإنشائية لإضافة سلسلة الاتصال الأساسي للجهاز والبروتوكول.

   String connString = "{IoT hub device connection string}";
   DeviceClient client = new DeviceClient(connString, protocol);
   

3. استخدم open لتوصيل الجهاز بمركز IoT. إذا كان العميل مفتوحا بالفعل، فإن الأسلوب لا يفعل شيئا.

   client.open(true);
   

المصادقة باستخدام شهادة X.509

لتوصيل جهاز ب IoT Hub باستخدام شهادة X.509:

1. إنشاء كائن SSLContext باستخدام buildSSLContext.
2. SSLContext أضف المعلومات إلى كائن ClientOptions.
3. اتصل ب DeviceClient باستخدام ClientOptions المعلومات لإنشاء اتصال Device-to-IoT Hub.

يوضح هذا المثال قيم معلمات إدخال الشهادة كمتغيرات محلية للوضوح. في نظام الإنتاج، قم بتخزين معلمات الإدخال الحساسة في متغيرات البيئة أو موقع تخزين آخر أكثر أمانا. على سبيل المثال، استخدم Environment.GetEnvironmentVariable("PUBLICKEY") لقراءة متغير بيئة سلسلة شهادة المفتاح العام.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

• مصادقة الهويات باستخدام شهادات X.509
• البرنامج التعليمي: إنشاء الشهادات وتحميلها للاختبار

نماذج التعليمات البرمجية

للحصول على نماذج العمل لمصادقة شهادة X.509 للجهاز، راجع:

• عينة إرسال وتلقي x509
• إرسال الحدث x509

استرداد جهاز مزدوج وعرضه

بعد فتح اتصال العميل، اتصل ب getTwin لاسترداد خصائص التوأم الحالية في كائن Twin .

على سبيل المثال:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

تحديث خصائص الجهاز المزدوج المبلغ عنها

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

لتحديث الخصائص المبلغ عنها:

1. استدعاء getReportedProperties لجلب الخصائص المزدوجة المبلغ عنها في كائن TwinCollection .

2. استخدم put لتحديث خاصية تم الإبلاغ عنها داخل TwinCollection الكائن. استدعاء put لكل تحديث خاصية تم الإبلاغ عنه.

3. استخدم updateReportedProperties لتطبيق مجموعة الخصائص التي تم الإبلاغ عنها التي تم تحديثها باستخدام put الأسلوب .

على سبيل المثال:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

الاشتراك في تغييرات الخاصية المطلوبة

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

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

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

في هذا المثال، تقوم الخاصية DesiredPropertiesUpdatedHandler المطلوبة بتغيير استدعاءات معالج رد الاتصال getDesiredProperties لاسترداد تغييرات الخاصية، ثم طباعة الخصائص المزدوجة المحدثة.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

نموذج جهاز SDK

يتضمن Azure IoT SDK ل Java عينة عمل لاختبار مفاهيم تطبيق الجهاز الموضحة في هذه المقالة. لمزيد من المعلومات، راجع نموذج الجهاز المزدوج.

إنشاء تطبيق خلفية

يصف هذا القسم كيفية إنشاء تطبيق خلفية:

• تحديث علامات الجهاز المزدوجة
• الاستعلام عن الأجهزة باستخدام عوامل التصفية على العلامات والخصائص

ServiceClient تحتوي فئة DeviceTwin على أساليب يمكن للخدمات استخدامها للوصول إلى توائم الجهاز.

عبارات استيراد الخدمة

استخدم عبارات استيراد الخدمة التالية للوصول إلى Azure IoT SDK ل Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

الاتصال بـ IoT hub

يمكنك توصيل خدمة خلفية ب IoT Hub باستخدام الطرق التالية:

• نهج الوصول المشترك
• Microsoft Entra

الاتصال باستخدام نهج وصول مشترك

استخدم منشئ DeviceTwin لإنشاء الاتصال بمركز IoT. DeviceTwin يعالج الكائن الاتصال مع مركز IoT الخاص بك.

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

يمثل كائن DeviceTwinDevice توأم الجهاز بخصائصه وعلاماته.

على سبيل المثال:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

الاتصال باستخدام Microsoft Entra

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

للحصول على نظرة عامة حول مصادقة Java SDK، راجع مصادقة Azure باستخدام Java وAzure Identity.

للتبسيط، يركز هذا القسم على وصف المصادقة باستخدام سر العميل.

تكوين تطبيق Microsoft Entra

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

• سر العميل
• شهادة
• بيانات اعتماد الهوية الموحدة

قد تتطلب تطبيقات Microsoft Entra أذونات دور محددة اعتمادا على العمليات التي يتم تنفيذها. على سبيل المثال، مطلوب IoT Hub Twin Contributor لتمكين الوصول للقراءة والكتابة إلى جهاز IoT Hub وتوائم الوحدة النمطية. لمزيد من المعلومات، راجع إدارة الوصول إلى IoT Hub باستخدام تعيين دور Azure RBAC.

لمزيد من المعلومات حول إعداد تطبيق Microsoft Entra، راجع التشغيل السريع: تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft.

المصادقة باستخدام DefaultAzureCredential

أسهل طريقة لاستخدام Microsoft Entra لمصادقة تطبيق الواجهة الخلفية هي استخدام DefaultAzureCredential، ولكن يوصى باستخدام طريقة مختلفة في بيئة إنتاج بما في ذلك طريقة معينة TokenCredential أو موزعة.ChainedTokenCredential لمزيد من المعلومات حول إيجابيات وسلبيات استخدام DefaultAzureCredential، راجع سلاسل بيانات الاعتماد في مكتبة عميل Azure Identity ل Java.

يدعم DefaultAzureCredential آليات مصادقة مختلفة ويحدد نوع بيانات الاعتماد المناسب استنادا إلى البيئة التي ينفذ فيها. يحاول استخدام أنواع بيانات اعتماد متعددة بترتيب حتى يعثر على بيانات اعتماد عاملة.

يمكنك مصادقة بيانات اعتماد تطبيق Microsoft Entra باستخدام DefaultAzureCredentialBuilder. احفظ معلمات الاتصال مثل معرف المستأجر السري للعميل ومعرف العميل والقيم السرية للعميل كمتغيرات بيئية. TokenCredential بمجرد إنشاء ، قم بتمريره إلى ServiceClient أو منشئ آخر كمعلمة "بيانات الاعتماد".

في هذا المثال، DefaultAzureCredentialBuilder يحاول مصادقة اتصال من القائمة الموضحة في DefaultAzureCredential. نتيجة مصادقة Microsoft Entra الناجحة هي بيانات اعتماد رمز أمان يتم تمريرها إلى منشئ مثل ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

المصادقة باستخدام ClientSecretCredentialBuilder

يمكنك استخدام ClientSecretCredentialBuilder لإنشاء بيانات اعتماد باستخدام معلومات سرية للعميل. إذا نجحت، يقوم هذا الأسلوب بإرجاع TokenCredential الذي يمكن تمريره إلى ServiceClient أو منشئ آخر كمعلمة "بيانات الاعتماد".

في هذا المثال، تمت إضافة سر عميل تسجيل تطبيق Microsoft Entra ومعرف العميل وقيم معرف المستأجر إلى متغيرات البيئة. يتم استخدام متغيرات البيئة هذه من قبل ClientSecretCredentialBuilder لإنشاء بيانات الاعتماد.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

فئات المصادقة الأخرى

يتضمن Java SDK أيضا هذه الفئات التي تصادق تطبيق الواجهة الخلفية باستخدام Microsoft Entra:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• بيئة معتمدة
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

نماذج التعليمات البرمجية

للحصول على نماذج العمل لمصادقة خدمة Microsoft Entra، راجع نموذج المصادقة المستندة إلى الدور.

تحديث الحقول المزدوجة للجهاز

لتحديث الحقول المزدوجة للجهاز:

1. استخدام getTwin لاسترداد الحقول المزدوجة للجهاز الحالي

   يسترد هذا المثال الحقول المزدوجة للجهاز ويطبعها:

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. استخدام كائن HashSetadd لمجموعة من أزواج علامات التوأم

3. استخدام setTags لإضافة مجموعة من أزواج العلامات من كائن tags إلى كائن DeviceTwinDevice

4. استخدام updateTwin لتحديث التوأم في مركز IoT

   يحدث هذا المثال المنطقة والعلامات المزدوجة لجهاز المصنع لتوائم الجهاز:

   // Update device twin tags if they are different
   // from the existing values
   String currentTags = device.tagsToString();
   if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
   
   // Create the tags and attach them to the DeviceTwinDevice object
   Set<Pair> tags = new HashSet<Pair>();
   tags.add(new Pair("region", region));
   tags.add(new Pair("plant", plant));
   device.setTags(tags);
   
   // Update the device twin in IoT Hub
   System.out.println("Updating device twin");
   twinClient.updateTwin(device);
   }
   
   // Retrieve and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

إنشاء استعلام مزدوج للجهاز

يوضح هذا القسم استعلامين لجهاز مزدوج. استعلامات الجهاز المزدوج هي استعلامات تشبه SQL التي ترجع مجموعة نتائج من توائم الجهاز.

تحتوي فئة Query على أساليب يمكن استخدامها لإنشاء استعلامات على غرار SQL إلى IoT Hub للتوائم أو المهام أو وظائف الجهاز أو البيانات الأولية.

لإنشاء استعلام جهاز:

1. استخدام createSqlQuery لإنشاء استعلام SQL المزدوج

2. استخدام queryTwin لتنفيذ الاستعلام

3. استخدم hasNextDeviceTwin للتحقق مما إذا كان هناك جهاز مزدوج آخر في مجموعة النتائج

4. استخدام getNextDeviceTwin لاسترداد توأم الجهاز التالي من مجموعة النتائج

ترجع استعلامات المثال التالي 100 جهاز كحد أقصى.

يحدد هذا الاستعلام المثال فقط توائم الجهاز للأجهزة الموجودة في مصنع Redmond43 .

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

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

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

عينة خدمة SDK

يوفر Azure IoT SDK ل Java عينة عمل لتطبيق خدمة يعالج المهام المزدوجة للجهاز. لمزيد من المعلومات، راجع نموذج الجهاز المزدوج.

• Python SDK - يوصى باستخدام Python الإصدار 3.7 أو أحدث . تأكد من استخدام التثبيت 32 بت أو 64 بت كما هو مطلوب من قبل الإعداد الخاص بك. عند المطالبة في أثناء التثبيت، تأكد من إضافة Python إلى متغيرات البيئة الخاصة بالنظام الأساسي.

نظرة عامة

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

تثبيت الحزم

يجب تثبيت مكتبة جهاز azure-iot لإنشاء تطبيقات الجهاز.

pip install azure-iot-device

يجب تثبيت مكتبة azure-iot-hub لإنشاء تطبيقات خدمة الواجهة الخلفية.

pip install azure-iot-hub

إنشاء تطبيق جهاز

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

تحتوي فئة IoTHubDeviceClient على أساليب يمكن استخدامها للعمل مع توائم الجهاز.

يصف هذا القسم كيفية إنشاء التعليمات البرمجية لتطبيق الجهاز التي:

• استرداد جهاز مزدوج وفحص الخصائص التي تم الإبلاغ عنها
• تصحيح خصائص الجهاز المزدوج المبلغ عنها

عبارة استيراد الجهاز

أضف هذه التعليمة البرمجية IoTHubDeviceClient لاستيراد الوظائف من azure.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

توصيل جهاز بـ IoT Hub

يمكن مصادقة تطبيق الجهاز باستخدام IoT Hub باستخدام الطرق التالية:

• مفتاح الوصول المشترك
• شهادة X.509

المصادقة باستخدام مفتاح وصول مشترك

لتوصيل جهاز ب IoT Hub:

1. اتصل create_from_connection_string لإضافة سلسلة الاتصال الأساسي للجهاز.
2. اتصل بالاتصال لتوصيل عميل الجهاز.

على سبيل المثال:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

المصادقة باستخدام شهادة X.509

لتوصيل جهاز ب IoT Hub باستخدام شهادة X.509:

1. استخدم create_from_x509_certificate لإضافة معلمات شهادة X.509
2. الاتصال بالاتصال لتوصيل عميل الجهاز

يوضح هذا المثال قيم معلمات إدخال الشهادة كمتغيرات محلية للوضوح. في نظام الإنتاج، قم بتخزين معلمات الإدخال الحساسة في متغيرات البيئة أو موقع تخزين آخر أكثر أمانا. على سبيل المثال، استخدم os.getenv("HOSTNAME") لقراءة متغير بيئة اسم المضيف.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

• مصادقة الهويات باستخدام شهادات X.509
• البرنامج التعليمي: إنشاء الشهادات وتحميلها للاختبار

نماذج التعليمات البرمجية

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

استرداد توأم جهاز وفحص الخصائص المبلغ عنها

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

اتصل get_twin للحصول على توأم الجهاز من خدمة Azure IoT Hub. يتم وضع المعلومات المزدوجة في متغير يمكن طباعته أو فحصه.

يسترد هذا المثال توأم الجهاز ويستخدم print الأمر لعرض الجهاز المزدوج بتنسيق JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

تصحيح خصائص الجهاز المزدوج المبلغ عنها

يمكنك تطبيق تصحيح لتحديث الخصائص المبلغ عنها للجهاز بتنسيق JSON.

لتطبيق تصحيح لتحديث الخصائص المبلغ عنها:

1. تعيين خاصية تم الإبلاغ عنها تصحيح JSON إلى متغير.
2. اتصل patch_twin_reported_properties لتطبيق تصحيح JSON على الخصائص المبلغ عنها. هذا استدعاء متزامن، ما يعني أن هذه الدالة لا ترجع حتى يتم إرسال التصحيح إلى الخدمة وإقراره.

إذا patch_twin_reported_properties أرجعت خطأ، فإن هذه الدالة ترفع الخطأ المقابل.

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

يمكنك أيضا استدعاء هذه الطرق لتحديث توائم الجهاز:

• استدعاء replace_twin لاستبدال علامات الجهاز المزدوجة والخصائص المطلوبة.
• اتصل update_twin لتحديث علامات الجهاز المزدوجة والخصائص المطلوبة.

معالج تصحيح الخصائص المطلوبة الواردة

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

يقوم هذا المثال بإعداد معالج تصحيح الخصائص المطلوب المسمى twin_patch_handler.

على سبيل المثال:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

يتلقى twin_patch_handler ويطبع تحديثات خاصية JSON المطلوبة.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

عينات جهاز SDK

يتضمن Azure IoT SDK ل Python العينات التالية:

• get_twin - الاتصال بجهاز واسترداد معلومات التوأم.
• update_twin_reported_properties - تحديث الخصائص المزدوجة المبلغ عنها.
• receive_twin_desired_properties - تلقي وتحديث الخصائص المطلوبة.

إنشاء تطبيق خلفية

يتصل تطبيق الواجهة الخلفية بجهاز من خلال IoT Hub ويمكنه قراءة الخصائص التي تم الإبلاغ عنها والخصائص المطلوبة للجهاز وكتابة الخصائص المطلوبة للجهاز وتشغيل استعلامات الجهاز.

يصف هذا القسم كيفية إنشاء تطبيق خلفية من أجل:

• تحديث العلامات المزدوجة والخصائص المطلوبة
• الاستعلام عن الأجهزة باستخدام عوامل التصفية على العلامات والخصائص

تعرض فئة IoTHubRegistryManager جميع الطرق المطلوبة لإنشاء تطبيق خلفية للتفاعل مع توائم الجهاز من الخدمة.

الاتصال بمركز IoT

يمكنك توصيل خدمة خلفية ب IoT Hub باستخدام الطرق التالية:

• نهج الوصول المشترك
• Microsoft Entra

الاتصال باستخدام نهج وصول مشترك

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

على سبيل المثال:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

الاتصال باستخدام Microsoft Entra

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

للحصول على نظرة عامة حول مصادقة Python SDK، راجع مصادقة تطبيقات Python على خدمات Azure باستخدام Azure SDK ل Python

تكوين تطبيق Microsoft Entra

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

• سر العميل
• شهادة
• بيانات اعتماد الهوية الموحدة

قد تتطلب تطبيقات Microsoft Entra أذونات دور محددة اعتمادا على العمليات التي يتم تنفيذها. على سبيل المثال، مطلوب IoT Hub Twin Contributor لتمكين الوصول للقراءة والكتابة إلى جهاز IoT Hub وتوائم الوحدة النمطية. لمزيد من المعلومات، راجع إدارة الوصول إلى IoT Hub باستخدام تعيين دور Azure RBAC.

لمزيد من المعلومات حول إعداد تطبيق Microsoft Entra، راجع التشغيل السريع: تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft.

المصادقة باستخدام DefaultAzureCredential

أسهل طريقة لاستخدام Microsoft Entra لمصادقة تطبيق الواجهة الخلفية هي استخدام DefaultAzureCredential، ولكن يوصى باستخدام طريقة مختلفة في بيئة إنتاج بما في ذلك طريقة معينة TokenCredential أو موزعة.ChainedTokenCredential للتبسيط، يصف هذا القسم المصادقة باستخدام DefaultAzureCredential وسر العميل. لمزيد من المعلومات حول إيجابيات وسلبيات استخدام DefaultAzureCredential، راجع سلاسل بيانات الاعتماد في مكتبة عميل Azure Identity ل Python.

يدعم DefaultAzureCredential آليات مصادقة مختلفة ويحدد نوع بيانات الاعتماد المناسب استنادا إلى البيئة التي ينفذ فيها. يحاول استخدام أنواع بيانات اعتماد متعددة بترتيب حتى يعثر على بيانات اعتماد عاملة.

يتطلب Microsoft Entra حزمة الاستيراد هذه والبيان المقابل import :

pip install azure-identity

from azure.identity import DefaultAzureCredential

في هذا المثال، تمت إضافة سر عميل تسجيل تطبيق Microsoft Entra ومعرف العميل ومعرف المستأجر إلى متغيرات البيئة. يتم استخدام متغيرات البيئة هذه من قبل DefaultAzureCredential لمصادقة التطبيق. نتيجة مصادقة Microsoft Entra الناجحة هي بيانات اعتماد رمز أمان يتم تمريرها إلى أسلوب اتصال IoT Hub.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

يمكن بعد ذلك تمرير AccessToken الناتج إلى from_token_credential للاتصال ب IoT Hub لأي عميل SDK يقبل بيانات اعتماد Microsoft Entra:

• IoTHubRegistryManager لإنشاء اتصال خدمة ب IoT Hub باستخدام بيانات اعتماد الرمز المميز ل Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential يتطلب معلمتين:

• عنوان URL لخدمة Azure - يجب أن يكون عنوان URL لخدمة Azure بالتنسيق {Your Entra domain URL}.azure-devices.net دون https:// بادئة. على سبيل المثال، MyAzureDomain.azure-devices.net
• الرمز المميز لبيانات اعتماد Azure

في هذا المثال، يتم الحصول على بيانات اعتماد Azure باستخدام DefaultAzureCredential. ثم يتم توفير IoTHubRegistryManager.from_token_credential عنوان URL لخدمة Azure وبيانات الاعتماد لإنشاء الاتصال ب IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

نماذج التعليمات البرمجية

للحصول على نماذج العمل لمصادقة خدمة Microsoft Entra، راجع مكتبة مصادقة Microsoft (MSAL) ل Python.

تحديث العلامات المزدوجة والخصائص المطلوبة

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

1. اتصل get_twin للحصول على الإصدار الحالي من الجهاز المزدوج
2. استخدم الفئة Twin لإضافة علامات وخصائص بتنسيق JSON.
3. اتصل update_twin لتطبيق التصحيح على توأم الجهاز. يمكنك أيضا استخدام replace_twin لاستبدال الخصائص والعلامات المطلوبة لجهاز مزدوج.

يقوم هذا المثال بتحديث معلومات العلامة regionplant وتعيين الخاصية power_level المطلوبة إلى 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

إنشاء استعلام مزدوج للجهاز

يمكنك الاستعلام عن معلومات الجهاز المزدوج باستخدام استعلامات الجهاز المزدوج. استعلامات الجهاز المزدوج هي استعلامات تشبه SQL التي ترجع مجموعة نتائج من توائم الجهاز.

لاستخدام استعلام توأم الجهاز:

1. استخدم كائن QuerySpecification لتعريف طلب استعلام يشبه SQL.

2. استخدم query_iot_hub للاستعلام عن IoTHub واسترداد معلومات الجهاز المزدوج باستخدام مواصفات الاستعلام الشبيهة ب SQL.

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

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

عينة خدمة SDK

يوفر Azure IoT SDK ل Python عينة عمل لتطبيق خدمة يعالج المهام المزدوجة للجهاز. لمزيد من المعلومات، راجع نموذج استعلام إدارة التسجيل.

• يتطلب Node.js الإصدار 10.0.x أو أحدث

نظرة عامة

توضح هذه المقالة كيفية استخدام Azure IoT SDK Node.js لإنشاء رمز تطبيق خدمة الجهاز والواجهة الخلفية لتوائم الجهاز.

إنشاء تطبيق جهاز

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

يصف هذا القسم كيفية استخدام حزمة azure-iot-device في Azure IoT SDK Node.js لإنشاء تطبيق جهاز من أجل:

• استرداد توأم جهاز وفحص الخصائص المبلغ عنها
• تحديث خصائص الجهاز المزدوج المبلغ عنها
• تلقي إشعار بتغييرات الخاصية المطلوبة

تثبيت حزمة SDK للجهاز

قم بتشغيل هذا الأمر لتثبيت Azure-iot-device SDK على جهاز التطوير الخاص بك:

npm install azure-iot-device --save

توصيل جهاز بـ IoT Hub

يمكن مصادقة تطبيق الجهاز باستخدام IoT Hub باستخدام الطرق التالية:

• شهادة X.509
• مفتاح الوصول المشترك

المصادقة باستخدام شهادة X.509

يتم إرفاق شهادة X.509 بنقل اتصال الجهاز إلى مركز IoT.

لتكوين اتصال Device-to-IoT Hub باستخدام شهادة X.509:

1. اتصل منConnectionString لإضافة وحدة الجهاز أو الهوية سلسلة الاتصال، ونوع النقل إلى Client الكائن. أضف x509=true إلى سلسلة الاتصال للإشارة إلى إضافة شهادة إلى DeviceClientOptions. على سبيل المثال:

   • سلسلة الاتصال الجهاز:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

   • وحدة نمطية للهوية سلسلة الاتصال:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

2. تكوين متغير JSON مع تفاصيل الشهادة وتمريره إلى DeviceClientOptions.

3. استدعاء setOptions لإضافة شهادة ومفتاح X.509 (واختياريا، عبارة المرور) إلى نقل العميل.

4. الاتصال مفتوح لفتح الاتصال من الجهاز إلى IoT Hub.

يوضح هذا المثال معلومات تكوين الشهادة داخل متغير JSON. يتم تمرير تكوين clientOptions الشهادة إلى setOptions، ويتم فتح الاتصال باستخدام open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

• مصادقة الهويات باستخدام شهادات X.509
• إنشاء الشهادات وتحميلها للاختبار

Code sample

للحصول على نموذج عمل لمصادقة شهادة الجهاز X.509، راجع نموذج بسيط للجهاز X.509.

المصادقة باستخدام مفتاح وصول مشترك

تحتوي حزمة azure-iot-device على كائنات واجهة مع أجهزة IoT. تتضمن فئة Twin كائنات خاصة بتوائم. يصف هذا القسم التعليمات البرمجية Client للفئة المستخدمة لقراءة وكتابة بيانات الجهاز المزدوجة.

اختيار بروتوكول نقل

Client يدعم الكائن هذه البروتوكولات:

• Amqp
• Http - عند استخدام Http، يتحقق المثيل Client من الرسائل من IoT Hub بشكل غير متكرر (بحد أدنى كل 25 دقيقة).
• Mqtt
• MqttWs
• AmqpWs

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

على سبيل المثال، يقوم هذا الأمر بتثبيت Mqtt البروتوكول:

npm install azure-iot-device-mqtt --save

لمزيد من المعلومات حول الاختلافات بين دعم MQTT وAMQP وHTTPS، راجع إرشادات الاتصالات من السحابة إلى الجهاز واختيار بروتوكول اتصال.

إنشاء وحدة نمطية للعميل

Client إنشاء وحدة نمطية باستخدام الحزمة المثبتة.

على سبيل المثال:

const Client = require('azure-iot-device').Client;

إنشاء وحدة نمطية للبروتوكول

Protocol إنشاء وحدة نمطية باستخدام حزمة نقل مثبتة.

يعين هذا المثال بروتوكول MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

إضافة سلسلة الاتصال الجهاز وبروتوكول النقل

استدعاء منConnectionString لتوفير معلمات اتصال الجهاز:

• connStr - سلسلة الاتصال يغلف أذونات "اتصال الجهاز" لمركز IoT. يحتوي سلسلة الاتصال على اسم المضيف ومعرف الجهاز ومفتاح الوصول المشترك بهذا التنسيق: "HostName=<iothub_host_name>؛ معرف الجهاز=<device_id>؛ SharedAccessKey=<device_key>".
• transportCtor - بروتوكول النقل.

يستخدم Mqtt هذا المثال بروتوكول النقل:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

فتح الاتصال ب IoT Hub

استخدم الأسلوب المفتوح لفتح اتصال بين جهاز IoT ومركز IoT. يستخدم .catch(err) لالتقاط خطأ وتنفيذ التعليمات البرمجية للمعالج.

على سبيل المثال:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

استرداد توأم جهاز وفحص الخصائص المبلغ عنها

اتصل ب getTwin لاسترداد معلومات الجهاز المزدوج الحالية في كائن Twin .

على سبيل المثال:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

تحديث خصائص الجهاز المزدوج المبلغ عنها

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

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

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

تلقي إشعار بتغييرات الخاصية المطلوبة

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

يمكن أن يتخذ مستمع حدث الخاصية المطلوب أحد النماذج التالية:

• تلقي جميع التصحيحات باستخدام معالج أحداث واحد
• تلقي حدث إذا تغير أي شيء ضمن تجميع الخصائص
• تلقي حدث لتغيير خاصية واحدة

تلقي جميع التصحيحات باستخدام معالج أحداث واحد

يمكنك إنشاء وحدة استماع لتلقي أي تغيير في الخاصية المطلوبة.

يقوم رمز المثال هذا إخراج أي خصائص يتم تلقيها من الخدمة.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

تلقي حدث إذا تغير أي شيء ضمن تجميع الخصائص

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

على سبيل المثال:

1. minTemperature تقع الخاصيتان و maxTemperature ضمن مجموعة خصائص تسمى properties.desired.climate changes.

2. يطبق تطبيق خدمة الواجهة الخلفية هذا التصحيح للتحديث minTemperature والخصائص maxTemperature المطلوبة:

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

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

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

تلقي حدث لتغيير خاصية واحدة

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

1. يطبق تطبيق الواجهة الخلفية تصحيح الخاصية المطلوب هذا:

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. يتم تشغيل وحدة الاستماع فقط عند تغيير الخاصية fanOn :

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

عينات SDK للجهاز

يحتوي Azure IoT SDK ل Node.js على عينتين توأم للجهاز:

• نموذج بسيط لجهاز مزدوج

• نموذج بسيط لجهاز مزدوج مع SAS

إنشاء تطبيق خلفية

يتصل تطبيق الواجهة الخلفية بجهاز من خلال IoT Hub ويمكنه قراءة الخصائص التي تم الإبلاغ عنها والخصائص المطلوبة للجهاز وكتابة الخصائص المطلوبة للجهاز وتشغيل استعلامات الجهاز.

يصف هذا القسم كيفية إنشاء تطبيق خلفية:

• استرداد وتحديث توأم الجهاز
• إنشاء استعلام مزدوج للجهاز

تثبيت حزمة SDK للخدمة

قم بتشغيل هذا الأمر لتثبيت azure-iothub على جهاز التطوير الخاص بك:

npm install azure-iothub --save

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

الاتصال بمركز IoT

يمكنك توصيل خدمة خلفية ب IoT Hub باستخدام الطرق التالية:

• نهج الوصول المشترك
• Microsoft Entra

الاتصال باستخدام نهج وصول مشترك

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

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

الاتصال باستخدام Microsoft Entra

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

للحصول على نظرة عامة على مصادقة Node.js SDK، راجع:

• الشروع في العمل مع مصادقة المستخدم على Azure
• مكتبة عميل Azure Identity لـ JavaScript

تكوين تطبيق Microsoft Entra

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

• سر العميل
• شهادة
• بيانات اعتماد الهوية الموحدة

قد تتطلب تطبيقات Microsoft Entra أذونات دور محددة اعتمادا على العمليات التي يتم تنفيذها. على سبيل المثال، مطلوب IoT Hub Twin Contributor لتمكين الوصول للقراءة والكتابة إلى جهاز IoT Hub وتوائم الوحدة النمطية. لمزيد من المعلومات، راجع إدارة الوصول إلى IoT Hub باستخدام تعيين دور Azure RBAC.

لمزيد من المعلومات حول إعداد تطبيق Microsoft Entra، راجع التشغيل السريع: تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft.

المصادقة باستخدام DefaultAzureCredential

أسهل طريقة لاستخدام Microsoft Entra لمصادقة تطبيق الواجهة الخلفية هي استخدام DefaultAzureCredential، ولكن يوصى باستخدام طريقة مختلفة في بيئة إنتاج بما في ذلك طريقة معينة TokenCredential أو موزعة.ChainedTokenCredential للتبسيط، يصف هذا القسم المصادقة باستخدام DefaultAzureCredential وسر العميل. لمزيد من المعلومات حول إيجابيات وسلبيات استخدام DefaultAzureCredential، راجع سلاسل بيانات الاعتماد في مكتبة عميل Azure Identity ل JavaScript

يدعم DefaultAzureCredential آليات مصادقة مختلفة ويحدد نوع بيانات الاعتماد المناسب استنادا إلى البيئة التي ينفذ فيها. يحاول استخدام أنواع بيانات اعتماد متعددة بترتيب حتى يعثر على بيانات اعتماد عاملة.

يتطلب Microsoft Entra هذه الحزمة:

npm install --save @azure/identity

في هذا المثال، تمت إضافة سر عميل تسجيل تطبيق Microsoft Entra ومعرف العميل ومعرف المستأجر إلى متغيرات البيئة. يتم استخدام متغيرات البيئة هذه من قبل DefaultAzureCredential لمصادقة التطبيق. نتيجة مصادقة Microsoft Entra الناجحة هي بيانات اعتماد رمز أمان يتم تمريرها إلى أسلوب اتصال IoT Hub.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

يمكن بعد ذلك تمرير الرمز المميز لبيانات الاعتماد الناتجة إلى fromTokenCredential للاتصال ب IoT Hub لأي عميل SDK يقبل بيانات اعتماد Microsoft Entra:

• التسجيل
• العميل
• JobClient

fromTokenCredential يتطلب معلمتين:

• عنوان URL لخدمة Azure - يجب أن يكون عنوان URL لخدمة Azure بالتنسيق {Your Entra domain URL}.azure-devices.net دون https:// بادئة. على سبيل المثال، MyAzureDomain.azure-devices.net
• الرمز المميز لبيانات اعتماد Azure

في هذا المثال، يتم الحصول على بيانات اعتماد Azure باستخدام DefaultAzureCredential. ثم يتم توفير Registry.fromTokenCredential عنوان URL لمجال Azure وبيانات الاعتماد لإنشاء الاتصال ب IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

نماذج التعليمات البرمجية

للحصول على نماذج العمل لمصادقة خدمة Microsoft Entra، راجع أمثلة هوية Azure.

استرداد وتحديث جهاز مزدوج

يمكنك إنشاء تصحيح يحتوي على العلامة وتحديثات الخصائص المطلوبة لجهاز مزدوج.

لتحديث توأم جهاز:

1. استدعاء getTwin لاسترداد الكائن المزدوج للجهاز.

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

1. اتصل بالتحديث لتحديث الجهاز المزدوج بالتصحيح.

في هذا المثال، يتم استرداد توأم الجهاز ل myDeviceId، ثم يتم تطبيق تصحيح على التوائم التي تحتوي على location تحديث علامة .region: 'US', plant: 'Redmond43'

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

إنشاء استعلام مزدوج للجهاز

يمكنك إنشاء استعلامات جهاز تشبه SQL لجمع المعلومات من توائم الجهاز.

استخدم createQuery لإنشاء استعلام يمكن تشغيله على مثيل مركز IoT للعثور على معلومات حول الأجهزة أو الوظائف.

createQuery يتضمن معلمتين:

• sqlQuery - الاستعلام المكتوب كسلسلة SQL.
• pageSize - العدد المطلوب من النتائج لكل صفحة (اختياري. الافتراضي: 1000، الحد الأقصى: 10000).

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

يحدد هذا الاستعلام المثال فقط توائم الجهاز للأجهزة الموجودة في Redmond43 المصنع.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

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

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

نموذج SDK للخدمة

يوفر Azure IoT SDK for Node.js عينة عمل لتطبيق خدمة يعالج المهام المزدوجة للجهاز. لمزيد من المعلومات، راجع Device Twin Backend Service - يستخدم هذا المشروع لإرسال تحديثات تصحيح الجهاز المزدوج لجهاز معين.