إرسال رسائل من السحابة إلى الجهاز وتلقيها

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

يصف هذا القسم كيفية تلقي رسائل من السحابة إلى الجهاز.

هناك خياران يمكن لتطبيق عميل الجهاز استخدامهما لتلقي الرسائل:

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

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

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

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

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

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

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

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

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

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

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

• transportType - بروتوكول النقل: تباينات إصدار HTTP 1 أو AMQP أو MQTT. AMQP هو الافتراضي. للاطلاع على كافة القيم المتوفرة، راجع تعداد نوع النقل.
• transportSettings - الواجهة المستخدمة لتحديد الإعدادات المختلفة الخاصة بالنقل ل DeviceClient و ModuleClient. لمزيد من المعلومات، راجع واجهة ITransportSettings.
• ClientOptions - الخيارات التي تسمح بتكوين مثيل عميل الجهاز أو الوحدة النمطية أثناء التهيئة.

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

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

رد الاتصال

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

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

يتوفر رد الاتصال فقط باستخدام هذه البروتوكولات:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_only

Http1 لا يدعم خيار البروتوكول عمليات رد الاتصال نظرا لأن أساليب SDK ستحتاج إلى الاستقصاء عن الرسائل المستلمة على أي حال، ما يهزم مبدأ رد الاتصال.

في هذا المثال، SetReceiveMessageHandlerAsync قم بإعداد أسلوب معالج رد الاتصال المسمى OnC2dMessageReceivedAsync، والذي يتم استدعاؤه في كل مرة يتم فيها تلقي رسالة.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

الاستقصاء

يستخدم الاستقصاء ReceiveAsync للتحقق من وجود رسائل.

يمكن أن تتخذ الدعوة إلى ReceiveAsync هذه النماذج:

• ReceiveAsync() - انتظر فترة المهلة الافتراضية لرسالة قبل المتابعة.
• ReceiveAsync (Timespan) - تلقي رسالة من قائمة انتظار الجهاز باستخدام مهلة محددة.
• ReceiveAsync (CancellationToken) - تلقي رسالة من قائمة انتظار الجهاز باستخدام رمز إلغاء. عند استخدام رمز إلغاء، لا يتم استخدام فترة المهلة الافتراضية.

عند استخدام نوع نقل HTTP 1 بدلا من MQTT أو AMQP، ReceiveAsync يرجع الأسلوب على الفور. النمط المدعوم للرسائل من سحابة إلى جهاز مع HTTP 1 هو أجهزة متصلة بشكل متقطع تتحقق من الرسائل بشكل غير متكرر (بحد أدنى كل 25 دقيقة). إصدار المزيد من HTTP 1 يتلقى النتائج في مركز IoT تقييد الطلبات. لمزيد من المعلومات حول الاختلافات بين دعم MQTT وAMQP وHTTP 1، راجع إرشادات الاتصالات من سحابة إلى جهاز واختيار بروتوكول اتصال.

أسلوب CompleteAsync

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

التخلي عن الرسالة أو رفضها أو انتهاء مهلتها

باستخدام بروتوكولات AMQP والإصدار 1 من HTTP، ولكن ليس بروتوكول MQTT، يمكن للجهاز أيضا:

• التخلي عن رسالة عن طريق استدعاء AbandonAsync. يؤدي هذا إلى الاحتفاظ برسالة IoT Hub في قائمة انتظار الجهاز للاستهلاك المستقبلي.
• رفض رسالة عن طريق استدعاء RejectAsync. يؤدي ذلك إلى إزالة الرسالة من قائمة انتظار الجهاز بشكل دائم.

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

لمزيد من المعلومات حول دورة حياة الرسائل من السحابة إلى الجهاز وكيفية معالجة IoT Hub للرسائل من السحابة إلى الجهاز، راجع إرسال رسائل من السحابة إلى الجهاز من IoT hub.

حلقة الاستقصاء

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

إذا كنت تستخدم ReceiveAsync مع قيمة مهلة أو المهلة الافتراضية، في التكرار الحلقي، ينتظر كل استدعاء ReceiveAsync لفترة المهلة المحددة. إذا ReceiveAsync انتهت المهلة null ، يتم إرجاع قيمة ويستمر التكرار الحلقي.

عند تلقي رسالة، يتم إرجاع كائن مهمة بواسطة الذي يجب تمريره ReceiveAsync إلى CompleteAsync. استدعاء لإعلام CompleteAsync IoT Hub بحذف الرسالة المحددة من قائمة انتظار الرسائل استنادا إلى المعلمة Task .

في هذا المثال، يستدعي ReceiveAsync التكرار الحلقي حتى يتم تلقي رسالة أو إيقاف حلقة الاستقصاء.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

تلقي نهج إعادة محاولة الرسائل

يمكن تعريف نهج إعادة محاولة رسالة عميل الجهاز باستخدام DeviceClient.SetRetryPolicy.

يتم تخزين مهلة إعادة محاولة الرسالة في الخاصية DeviceClient.OperationTimeoutInMilliseconds .

نموذج رسالة تلقي SDK

يتضمن .NET/C# SDK عينة تلقي رسالة تتضمن أساليب رسالة الاستلام الموضحة في هذا القسم.

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

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

يمكن لتطبيق الواجهة الخلفية للحل أيضا طلب وتلقي ملاحظات التسليم لرسالة تم إرسالها إلى IoT Hub والموجهة لتسليم الجهاز عبر قائمة انتظار الرسائل.

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

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

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

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

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

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

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

• transportType - Amqp أو Amqp_WebSocket_Only.
• transportSettings - إعدادات وكيل AMQP وHTTP لعميل الخدمة.
• ServiceClientOptions - الخيارات التي تسمح بتكوين مثيل عميل الخدمة أثناء التهيئة. لمزيد من المعلومات، راجع ServiceClientOptions.

ينشئ ServiceClient هذا المثال الكائن باستخدام سلسلة الاتصال IoT Hub والنقل الافتراضيAmqp.

static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.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، راجع نموذج المصادقة المستندة إلى الدور.

إرسال رسالة غير متزامنة من سحابة إلى جهاز

استخدم sendAsync لإرسال رسالة غير متزامنة من تطبيق عبر السحابة (IoT Hub) إلى الجهاز. يتم إجراء الاستدعاء باستخدام بروتوكول AMQP.

sendAsync يستخدم هذه المعلمات:

• deviceID - معرف السلسلة للجهاز الهدف.
• message - رسالة من السحابة إلى الجهاز. الرسالة من نوع رسالة ويمكن تنسيقها وفقا لذلك.
• timeout - قيمة مهلة اختيارية . الإعداد الافتراضي هو دقيقة واحدة إذا لم يتم تحديده.

يرسل هذا المثال رسالة اختبار إلى الجهاز الهدف بقيمة مهلة 10 ثوان.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

تلقي ملاحظات التسليم

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

لتلقي ملاحظات حول تسليم الرسائل:

• إنشاء الكائن feedbackReceiver
• إرسال رسائل باستخدام المعلمة Ack
• انتظر لتلقي الملاحظات

إنشاء كائن feedbackReceiver

استدعاء GetFeedbackReceiver لإنشاء كائن FeedbackReceiver . FeedbackReceiver يحتوي على الأساليب التي يمكن أن تستخدمها الخدمات لتنفيذ عمليات تلقي الملاحظات.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

إرسال الرسائل باستخدام معلمة Ack

يجب أن تتضمن كل رسالة قيمة لخاصية Ack لإقرار التسليم من أجل تلقي ملاحظات التسليم. Ack يمكن أن تكون الخاصية إحدى هذه القيم:

• بلا (افتراضي): لا يتم إنشاء رسالة ملاحظات.

• Positive: تلقي رسالة ملاحظات إذا تم إكمال الرسالة.

• Negative: تلقي رسالة ملاحظات إذا انتهت صلاحية الرسالة (أو تم الوصول إلى الحد الأقصى لعدد التسليم) دون إكمال الجهاز.

• Full: ملاحظات لكل من Positive والنتائج Negative .

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

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

انتظر لتلقي الملاحظات

CancellationTokenتعريف . ثم في التكرار الحلقي، اتصل ب ReceiveAsync بشكل متكرر، وافحص رسائل ملاحظات التسليم. ينتظر كل استدعاء ReceiveAsync فترة المهلة المحددة للكائن ServiceClient .

• ReceiveAsync إذا انتهت مهلة دون تلقي أي رسالة، ReceiveAsync يتم إرجاع null ويستمر التكرار الحلقي.
• إذا تم تلقي رسالة ملاحظات، يتم إرجاع كائن مهمة بواسطة الذي يجب تمريره ReceiveAsync إلى CompleteAsync مع رمز الإلغاء المميز. استدعاء لحذف CompleteAsync الرسالة المرسلة المحددة من قائمة انتظار الرسائل استنادا إلى المعلمة Task .
• إذا لزم الأمر، يمكن للتعليمة البرمجية المتلقية استدعاء AbandonAsync لوضع رسالة إرسال مرة أخرى في قائمة الانتظار.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

يوضح هذا المثال أسلوبا يتضمن هذه الخطوات.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

لاحظ أن نمط تلقي الملاحظات هذا مشابه للنمط المستخدم لتلقي رسائل من السحابة إلى الجهاز في تطبيق الجهاز.

إعادة اتصال عميل الخدمة

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

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

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

إرسال نهج إعادة محاولة الرسائل

ServiceClient يمكن تعريف نهج إعادة محاولة الرسالة باستخدام ServiceClient.SetRetryPolicy.

نموذج رسالة إرسال SDK

يتضمن .NET/C# SDK عينة عميل الخدمة التي تتضمن أساليب إرسال الرسالة الموضحة في هذا القسم.

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

يصف هذا القسم كيفية تلقي رسائل من السحابة إلى الجهاز باستخدام فئة DeviceClient من Azure IoT SDK ل Java.

لكي يتلقى تطبيق الجهاز المستند إلى Java رسائل من السحابة إلى الجهاز، يجب الاتصال ب IoT Hub، ثم إعداد مستمع رد الاتصال ومعالج الرسائل لمعالجة الرسائل الواردة من IoT Hub.

استيراد مكتبات Azure IoT Java SDK

تستخدم التعليمات البرمجية المشار إليها في هذه المقالة مكتبات SDK هذه.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

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

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

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

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

يتطلب إنشاء مثيل كائن DeviceClient هذه المعلمات:

• connString - سلسلة الاتصال جهاز IoT. سلسلة الاتصال هو مجموعة من أزواج قيم المفاتيح التي يتم فصلها بواسطة ';'، مع المفاتيح والقيم مفصولة ب '='. يجب أن يحتوي على قيم لهذه المفاتيح: HostName, DeviceId, and SharedAccessKey.
• بروتوكول النقل - DeviceClient يمكن للاتصال استخدام أحد بروتوكولات نقل IoTHubClientProtocol التالية. AMQP هو الأكثر تنوعا، ويسمح بالتحقق من الرسائل بشكل متكرر، ويسمح برفض الرسائل وإلغاءها. لا يدعم MQTT رفض الرسائل أو التخلي عن الأساليب:
  • AMQPS
  • AMQPS_WS
  • HTTPS
  • MQTT
  • MQTT_WS

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

static string connectionString = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

المصادقة باستخدام شهادة 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

تعيين أسلوب رد اتصال الرسالة

استخدم أسلوب setMessageCallback لتعريف أسلوب معالج الرسائل الذي يتم إعلامه عند تلقي رسالة من IoT Hub.

setMessageCallback يتضمن هذه المعلمات:

• callback - اسم أسلوب رد الاتصال. يمكن أن يكون null.
• context - سياق اختياري من النوع object. استخدم null إذا لم يتم تحديده.

في هذا المثال، يتم تمرير أسلوب مسمى callbackMessageCallback بدون معلمة سياق إلى setMessageCallback.

client.setMessageCallback(new MessageCallback(), null);

إنشاء معالج رد اتصال الرسائل

يتلقى معالج رسالة رد الاتصال ويعالج رسالة واردة تم تمريرها من قائمة انتظار رسائل IoT Hub.

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

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

خيارات التخلي عن الرسائل ورفضها

على الرغم من أنه يجب تلقي العدد الهائل من الرسائل الواردة إلى جهاز بنجاح والنتيجة في IotHubMessageResult.COMPLETE، فقد يكون من الضروري التخلي عن رسالة أو رفضها.

• باستخدام AMQP وHTTPS، ولكن ليس MQTT، يمكن للتطبيق:
  • IotHubMessageResult.ABANDON الرسالة. يعيد مركز IoT طلبه ويرسله مرة أخرى لاحقا.
  • IotHubMessageResult.REJECT الرسالة. لا يعيد مركز IoT طلب الرسالة ويزيل الرسالة بشكل دائم من قائمة انتظار الرسائل.
• العملاء الذين يستخدمون MQTT أو MQTT_WS لا يمكنهم ABANDON أو REJECT الرسائل.

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

لمزيد من المعلومات حول دورة حياة الرسائل من السحابة إلى الجهاز وكيفية معالجة IoT Hub للرسائل من السحابة إلى الجهاز، راجع إرسال رسائل من السحابة إلى الجهاز من IoT hub.

إنشاء أسلوب رد اتصال حالة الرسالة

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

في هذا المثال، IotHubConnectionStatusChangeCallbackLogger يتم تسجيل كطريقة رد اتصال تغيير حالة الاتصال.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

يتم تشغيل رد الاتصال وتم تمرير كائن ConnectionStatusChangeContext .

اتصل connectionStatusChangeContext.getNewStatus() للحصول على حالة الاتصال الحالية.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

يمكن أن تكون حالة الاتصال التي تم إرجاعها إحدى هذه القيم:

• IotHubConnectionStatus.DISCONNECTED
• IotHubConnectionStatus.DISCONNECTED_RETRYING
• IotHubConnectionStatus.CONNECTED

اتصل connectionStatusChangeContext.getNewStatusReason() للحصول على سبب تغيير حالة الاتصال.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

اتصل connectionStatusChangeContext.getCause() للعثور على سبب تغيير حالة الاتصال. getCause() قد يرجع null إذا لم تتوفر أي معلومات.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

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

فتح الاتصال بين الجهاز وIoT Hub

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

client.open(true);

نموذج رسالة تلقي SDK

HandleMessages: نموذج تطبيق جهاز مضمن مع Microsoft Azure IoT SDK ل Java، والذي يتصل بمركز IoT الخاص بك ويتلقى رسائل من السحابة إلى الجهاز.

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

يصف هذا القسم كيفية إرسال رسالة من سحابة إلى جهاز باستخدام فئة ServiceClient من Azure IoT SDK ل Java. يتصل تطبيق الواجهة الخلفية للحل بمركز IoT ويتم إرسال الرسائل إلى IoT Hub مرمزة بجهاز وجهة. يخزن IoT Hub الرسائل الواردة إلى قائمة انتظار الرسائل الخاصة به، ويتم تسليم الرسائل من قائمة انتظار رسائل IoT Hub إلى الجهاز الهدف.

يمكن لتطبيق الواجهة الخلفية للحل أيضا طلب وتلقي ملاحظات التسليم لرسالة تم إرسالها إلى IoT Hub والموجهة لتسليم الجهاز عبر قائمة انتظار الرسائل.

إضافة عبارة التبعية

أضف التبعية لاستخدام حزمة iothub-java-service-client في تطبيقك للاتصال بخدمة مركز IoT:

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

إضافة عبارات الاستيراد

أضف عبارات الاستيراد هذه لاستخدام Azure IoT Java SDK ومعالج الاستثناء.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

الاتصال بـ IoT hub

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

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

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

تعريف بروتوكول الاتصال

استخدم IotHubServiceClientProtocol لتحديد بروتوكول طبقة التطبيق المستخدم من قبل عميل الخدمة للاتصال بمركز IoT.

IotHubServiceClientProtocol يقبل AMQPS فقط قائمة التعداد أو AMQPS_WS .

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

إنشاء كائن ServiceClient

إنشاء كائن ServiceClient، وتوفير سلسلة الاتصال Iot Hub والبروتوكول.

String connectionString = "{yourhubconnectionstring}";
ServiceClient serviceClient (connectionString, protocol);

فتح الاتصال بين التطبيق وIoT Hub

افتح اتصال مرسل AMQP. ينشئ هذا الأسلوب الاتصال بين التطبيق ومركز IoT.

serviceClient.open();

الاتصال باستخدام 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، راجع نموذج المصادقة المستندة إلى الدور.

فتح جهاز استقبال ملاحظات لملاحظات تسليم الرسائل

يمكنك استخدام FeedbackReceiver لإرسال رسالة التسليم إلى ملاحظات IoT Hub. هو FeedbackReceiver جهاز استقبال متخصص يقوم أسلوبه Receive بإرجاع FeedbackBatch بدلا من Message.

في هذا المثال، FeedbackReceiver يتم إنشاء الكائن ويتم استدعاء العبارة open() لانتظار الملاحظات.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

إضافة خصائص الرسالة

يمكنك اختياريا استخدام setProperties لإضافة خصائص الرسالة. يتم تضمين هذه الخصائص في الرسالة المرسلة إلى الجهاز ويمكن استخراجها بواسطة تطبيق الجهاز عند الاستلام.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

إنشاء رسالة غير متزامنة وإرسالها

يخزن كائن الرسالة الرسالة التي سيتم إرسالها. في هذا المثال، يتم تسليم "رسالة من سحابة إلى جهاز".

استخدم setDeliveryAcknowledgement لطلب تسليم/عدم التسليم إلى إقرار قائمة انتظار رسائل IoT Hub. في هذا المثال، الإقرار المطلوب هو Full، إما تم تسليمه أو لم يتم تسليمه.

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

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

تلقي ملاحظات حول تسليم الرسائل

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

ينشئ FeedbackBatch هذا المثال المتلقي ويستدعي getEnqueuedTimeUtc، ويطبع وقت وضع الرسالة في قائمة الانتظار.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

إرسال عينات رسائل SDK

هناك نموذجان لرسالة الإرسال:

• نموذج عميل الخدمة - إرسال مثال الرسالة، #1.
• نموذج عميل الخدمة - إرسال مثال الرسالة، #2.

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

يصف هذا القسم كيفية تلقي رسائل من السحابة إلى الجهاز.

تتضمن فئة IoTHubDeviceClient أساليب لإنشاء اتصال متزامن من جهاز إلى Azure IoT Hub وتلقي الرسائل من IoT Hub.

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

pip install azure-iot-device

لكي يتلقى تطبيق الجهاز المستند إلى Python رسائل من السحابة إلى الجهاز، يجب الاتصال ب IoT Hub ثم إعداد معالج رسائل رد الاتصال لمعالجة الرسائل الواردة من IoT Hub.

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

أضف هذه التعليمة البرمجية 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.

معالجة إعادة الاتصال

IoTHubDeviceClient سيحاول بشكل افتراضي إعادة إنشاء اتصال تم إسقاطه. يخضع IoTHubDeviceClientسلوك إعادة الاتصال connection_retry والمعلمات connection_retry_interval .

إنشاء معالج رسائل

إنشاء دالة معالج الرسائل لمعالجة الرسائل الواردة إلى الجهاز. سيتم تعيين هذا بواسطة on_message_received (الخطوة التالية) كمعالج رسالة رد الاتصال.

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

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

تعيين معالج الرسائل

استخدم أسلوب on_message_received لتعيين أسلوب معالج الرسائل.

في هذا المثال، يتم إرفاق أسلوب معالج الرسائل المسمى message_handler بالكائن IoTHubDeviceClientclient . client ينتظر الكائن لتلقي رسالة من سحابة إلى جهاز من IoT Hub. تنتظر هذه التعليمة البرمجية ما يصل إلى 300 ثانية (5 دقائق) لرسالة، أو تخرج إذا تم الضغط على مفتاح لوحة المفاتيح.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

نموذج رسالة تلقي SDK

رسالة الاستلام - تلقي رسائل من السحابة إلى الجهاز (C2D) المرسلة من Azure IoT Hub إلى جهاز.

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

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

تعرض فئة IoTHubRegistryManager جميع الأساليب المطلوبة لإنشاء تطبيق خلفية للتفاعل مع الرسائل من السحابة إلى الجهاز من الخدمة. يجب تثبيت مكتبة azure-iot-hub لإنشاء تطبيقات خدمة الواجهة الخلفية.

pip install azure-iot-hub

استيراد كائن IoTHubRegistryManager

أضف العبارة التالية import . يتضمن IoTHubRegistryManager واجهات برمجة التطبيقات لعمليات IoT Hub Registry Manager.

from azure.iot.hub import IoTHubRegistryManager

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

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

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

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

الاتصال بمركز IoT باستخدام from_connection_string.

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

IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

الاتصال باستخدام 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، راجع نموذج المصادقة المستندة إلى الدور.

إنشاء رسالة وإرسالها

استخدم send_c2d_message لإرسال رسالة عبر السحابة (IoT Hub) إلى الجهاز.

send_c2d_message يستخدم هذه المعلمات:

• deviceID - معرف السلسلة للجهاز الهدف.
• message - رسالة من السحابة إلى الجهاز. الرسالة من النوع str (سلسلة).
• properties - مجموعة اختيارية من خصائص النوع dict. يمكن أن تحتوي الخصائص على خصائص التطبيق وخصائص النظام. القيمة الافتراضية هي {}.

يرسل هذا المثال رسالة اختبار إلى الجهاز الهدف.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

نموذج رسالة إرسال SDK

يوفر Azure IoT SDK ل Python عينة عمل لتطبيق خدمة يوضح كيفية إرسال رسالة من السحابة إلى الجهاز. لمزيد من المعلومات، راجع send_message.py يوضح كيفية إرسال رسالة من السحابة إلى الجهاز.

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

يصف هذا القسم كيفية تلقي رسائل من السحابة إلى الجهاز باستخدام حزمة azure-iot-device في Azure IoT SDK Node.js.

للحصول على تطبيق جهاز يستند إلى Node.js لتلقي رسائل من السحابة إلى الجهاز، يجب الاتصال ب IoT Hub، ثم إعداد مستمع رد الاتصال ومعالج الرسائل لمعالجة الرسائل الواردة من IoT Hub. يجب أن يكون تطبيق الجهاز قادرا أيضا على اكتشاف حالات قطع الاتصال ومعالجتها في حالة انقطاع اتصال رسالة Device-to-IoT Hub.

تثبيت حزم SDK

تحتوي حزمة azure-iot-device على كائنات واجهة مع أجهزة IoT. قم بتشغيل هذا الأمر لتثبيت 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.

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

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

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

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

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

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

npm install azure-iot-device-amqp --save

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

يعين هذا المثال بروتوكول AMQP إلى Protocol متغير. يتم تمرير متغير البروتوكول هذا إلى Client.fromConnectionString الأسلوب في قسم إضافة سلسلة الاتصال من هذه المقالة.

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

قدرات إكمال الرسالة ورفضها والتخلي عنها

يمكن استخدام أساليب إكمال الرسالة ورفضها والتخلي عنها اعتمادا على البروتوكول المختار.

AMQP وHTTP

يمكن أن تكمل عمليات نقل AMQP وHTTP رسالة أو ترفضها أو تتخلى عنها:

• Complete - لإكمال رسالة، يتم إعلام الخدمة التي أرسلت الرسالة من السحابة إلى الجهاز باستلام الرسالة. يزيل IoT Hub الرسالة من قائمة انتظار الرسائل. يأخذ الأسلوب شكل client.complete(message, callback function).
• رفض - لرفض رسالة، يتم إعلام الخدمة التي أرسلت الرسالة من السحابة إلى الجهاز بأن الرسالة لا تتم معالجتها بواسطة الجهاز. يزيل IoT Hub الرسالة بشكل دائم من قائمة انتظار الجهاز. يأخذ الأسلوب شكل client.reject(message, callback function).
• التخلي - للتخلي عن رسالة، يحاول IoT Hub على الفور إعادة إرسالها. يحتفظ IoT Hub بالرسالة في قائمة انتظار الجهاز للاستهلاك المستقبلي. يأخذ الأسلوب شكل client.abandon(message, callback function).

MQTT

لا يدعم MQTT إكمال الرسالة أو رفضها أو التخلي عن الدالات. بدلا من ذلك، يقبل MQTT رسالة بشكل افتراضي ويتم إزالة الرسالة من قائمة انتظار رسائل IoT Hub.

محاولات إعادة الحياة

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

إنشاء كائن عميل

إنشاء كائن Client باستخدام الحزمة المثبتة.

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

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

إنشاء كائن بروتوكول

إنشاء كائن Protocol باستخدام حزمة نقل مثبتة.

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

const Protocol = require('azure-iot-device-amqp').Amqp;

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

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

• connStr - سلسلة الاتصال الجهاز.
• transportCtor - بروتوكول النقل.

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

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

إنشاء معالج رسائل وارد

يتم استدعاء معالج الرسائل لكل رسالة واردة.

بعد تلقي رسالة بنجاح، إذا كنت تستخدم AMQP أو نقل HTTP، فاتصل client.complete بالأسلوب لإعلام IoT Hub بأنه يمكن إزالة الرسالة من قائمة انتظار الرسائل.

على سبيل المثال، يقوم معالج الرسائل هذا بطباعة معرف الرسالة والنص الأساسي للرسالة إلى وحدة التحكم، ثم يستدعي client.complete لإعلام IoT Hub بأنه قام بمعالجة الرسالة وأنه يمكن إزالتها بأمان من قائمة انتظار الجهاز. الاستدعاء إلى complete غير مطلوب إذا كنت تستخدم نقل MQTT ويمكن حذفه. مطلوب استدعاءcomplete لنقل AMQP أو HTTPS.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

إنشاء معالج قطع اتصال

يتم استدعاء معالج قطع الاتصال عند قطع الاتصال. معالج قطع الاتصال مفيد لتنفيذ التعليمات البرمجية لإعادة الاتصال.

يلتقط هذا المثال رسالة خطأ قطع الاتصال بوحدة التحكم ويعرضها.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

إضافة مستمعي الأحداث

يمكنك تحديد وحدات استماع الأحداث هذه باستخدام الأسلوب .on .

• معالج الاتصال
• معالج الأخطاء
• معالج قطع الاتصال
• معالج الرسائل

يتضمن هذا المثال معالجات الرسالة وقطع الاتصال المعرفة مسبقا.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

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

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

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

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

عينات جهاز SDK

يوفر Azure IoT SDK for Node.js عينة عمل لتطبيق جهاز يعالج تلقي الرسالة. لمزيد من المعلومات، راجع:

simple_sample_device - تطبيق جهاز يتصل بمركز IoT ويتلقى رسائل من السحابة إلى الجهاز.

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

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

يمكن لتطبيق الواجهة الخلفية للحل أيضا طلب وتلقي ملاحظات التسليم لرسالة تم إرسالها إلى IoT Hub والموجهة لتسليم الجهاز عبر قائمة انتظار الرسائل.

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

تحتوي حزمة azure-iothub على كائنات واجهة مع IoT Hub. توضح هذه المقالة التعليمات البرمجية Client للفئة التي ترسل رسالة من تطبيق إلى جهاز عبر IoT Hub.

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

npm install azure-iothub --save

تحميل وحدات العميل والرسائل

قم بتعريف كائن Client باستخدام Client الفئة من الحزمة azure-iothub .

قم بتعريف كائن Message باستخدام Message الفئة من الحزمة azure-iot-common .

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

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

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

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

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

استخدم منConnectionString للاتصال بمركز IoT.

في هذا المثال، serviceClient يتم إنشاء الكائن بنوع Amqp النقل.

var connectionString = '{IoT hub device connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

فتح اتصال العميل

Client استدعاء الأسلوب المفتوح لفتح اتصال بين تطبيق ومركز IoT.

open يمكن استدعاء مع أو بدون تحديد دالة رد الاتصال التي يتم استدعاؤها عند open اكتمال العملية.

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

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

الاتصال باستخدام 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.

إنشاء رسالة

يتضمن كائن الرسالة الرسالة غير المتزامنة من سحابة إلى جهاز. تعمل وظيفة الرسالة بنفس الطريقة عبر AMQP وMQTT وHTTP.

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

• ack - تقديم الملاحظات. موضح في القسم التالي.
• properties - خريطة تحتوي على مفاتيح سلسلة وقيم لتخزين خصائص الرسالة المخصصة.
• messageId - يستخدم لربط الاتصال ثنائي الاتجاه.

أضف نص الرسالة عند إنشاء مثيل لكائن الرسالة. في هذا المثال، 'Cloud to device message.' تتم إضافة رسالة.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

إقرار التسليم

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

يجب أن تتضمن كل رسالة لتلقي ملاحظات الرسالة قيمة لخاصية ack لإقرار التسليم. ack يمكن أن تكون الخاصية إحدى هذه القيم:

• بلا (افتراضي): لا يتم إنشاء رسالة ملاحظات.

• sent: تلقي رسالة ملاحظات إذا تم إكمال الرسالة.

• : تلقي رسالة ملاحظات إذا انتهت صلاحية الرسالة (أو تم الوصول إلى الحد الأقصى لعدد التسليم) دون إكمال الجهاز.

• full: ملاحظات لكل من النتائج المرسلة وغير المرسلة.

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

message.ack = 'full';

ربط متلقي الملاحظات بالرسالة

ترتبط Client دالة رد اتصال مستقبل ملاحظات الرسالة باستخدام getFeedbackReceiver.

يتلقى متلقي ملاحظات الرسالة وسيطتين:

• كائن الخطأ (يمكن أن يكون خاليا)
• كائن AmqpReceiver - يصدر الأحداث عند تلقي العميل رسائل ملاحظات جديدة.

تتلقى وظيفة المثال هذه رسالة ملاحظات التسليم وتطبعها إلى وحدة التحكم.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

تربط هذه التعليمة البرمجية دالة رد اتصال الملاحظات receiveFeedback بكائن الخدمة Client باستخدام getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

تعريف معالج نتائج إكمال الرسائل

يتم استدعاء دالة رد الاتصال الخاصة بإرسال الرسالة بعد إرسال كل رسالة.

تقوم وظيفة المثال هذه بطباعة نتائج عملية الرسالة send إلى وحدة التحكم. في هذا المثال، يتم توفير الدالة printResultFor كمعلمة للدالة الموضحة send في القسم التالي.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

إرسال رسالة

استخدم وظيفة الإرسال لإرسال رسالة غير متزامنة من سحابة إلى جهاز إلى تطبيق الجهاز من خلال IoT Hub.

send يدعم هذه المعلمات:

• deviceID - معرف الجهاز للجهاز الهدف.
• message - النص الأساسي للرسالة لإرسالها إلى الجهاز.
• done - الدالة الاختيارية لاستدعاء عند اكتمال العملية. يتم استدعاء Done مع وسيطتين:
  • كائن الخطأ (يمكن أن يكون فارغا).
  • عنصر استجابة خاص بالنقل مفيد للتسجيل أو تصحيح الأخطاء.

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

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

يوضح هذا المثال كيفية إرسال رسالة إلى جهازك ومعالجة رسالة الملاحظات عندما يقر الجهاز برسالة السحابة إلى الجهاز:

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

نموذج رسالة إرسال SDK

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

send_c2d_message.js - إرسال رسائل C2D إلى جهاز من خلال IoT Hub.