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

مقالة
07/02/2024

Azure IoT Hub هي خدمة مدارة بالكامل تمكن الاتصالات ثنائية الاتجاه، بما في ذلك رسائل السحابة إلى الجهاز (C2D) من النهايات الخلفية للحل إلى ملايين الأجهزة.

توضح هذه المقالة كيفية استخدام Azure IoT SDKs لإنشاء الأنواع التالية من التطبيقات:

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

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

إشعار

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

نظرة عامة

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

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

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

الإعلان عن كائن عميل خدمة
الاتصال بمركز IoT
إنشاء الرسالة وإرسالها
تلقي ملاحظات التسليم
تكوين نهج إعادة محاولة إرسال رسالة

فهم قائمة انتظار الرسائل

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

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

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

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

يقال إن تطبيق الجهاز الذي يتلقى رسالة ويعالجها بنجاح هو إكمال الرسالة. ومع ذلك، إذا لزم الأمر، يمكن للجهاز أيضا:

رفض الرسالة، مما يؤدي إلى تعيين IoT Hub إلى حالة الرسائل المهمل. لا يمكن للأجهزة التي تتصل عبر بروتوكول Message Queuing Telemetry Transport (MQTT) رفض الرسائل من السحابة إلى الجهاز.
تخلى عن الرسالة، مما يؤدي إلى إعادة مركز IoT إلى وضع الرسالة مرة أخرى في قائمة الانتظار، مع تعيين حالة الرسالة إلى Enqueued. لا يمكن للأجهزة التي تتصل عبر بروتوكول MQTT التخلي عن الرسائل من السحابة إلى الجهاز.

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

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

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

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

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

الإعلان عن كائن DeviceClient

يتضمن DeviceClient الأساليب والخصائص اللازمة لتلقي الرسائل من IoT Hub.

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

static DeviceClient deviceClient;

توفير معلمات الاتصال

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

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

يستدعي CreateFromConnectionString هذا المثال لتعريف DeviceClient مركز IoT الاتصال وإعدادات معرف الجهاز.

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

الاستقصاء

يستخدم الاستقصاء 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، بحيث ينتج عن تلقي نفس الرسالة عدة مرات نفس النتيجة.

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

باستخدام الاستقصاء، يستخدم التطبيق حلقة تعليمات برمجية تستدعي 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 ();
}

رد الاتصال

لتلقي رسائل رد الاتصال من السحابة إلى الجهاز في تطبيق الجهاز، يجب على التطبيق الاتصال بمركز 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.");

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

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

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

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

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

إرسال رسائل من السحابة إلى الجهاز

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

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

الإعلان عن كائن ServiceClient

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

static ServiceClient serviceClient;

توفير سلسلة الاتصال

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

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

ينشئ ServiceClient هذا المثال الكائن باستخدام سلسلة الاتصال IoT Hub.

static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

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

استخدم 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 timout 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. يجب أن يكون تطبيق الجهاز قادرا أيضا على اكتشاف حالات قطع الاتصال ومعالجتها في حالة انقطاع اتصال رسالة Device-to-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;

الإعلان عن كائن DeviceClient

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

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

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

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

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

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

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

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

في هذا المثال، يتم تمرير أسلوب مسمى callback MessageCallback بدون معلمة سياق إلى 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 الرسائل.

إشعار

إذا كنت تستخدم HTTPS بدلاً من MQTT أو AMQP كنقل، يتحقق مثيل DeviceClient من الرسائل من مركز إنترنت الأشياء بشكل غير متكرر (بحد أدنى كل 25 دقيقة). لمزيد من المعلومات حول الاختلافات بين دعم MQTT وAMQP وHTTPS، راجع إرشادات الاتصالات من السحابة إلى الجهاز واختيار بروتوكول اتصال.

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

يمكن للتطبيق استخدام 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 إلى الجهاز الهدف.

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

أضف التبعية لاستخدام حزمة 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;

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

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

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

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

إنشاء كائن ServiceClient

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

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

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

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

serviceClient.open();

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

يمكنك استخدام 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.

تثبيت مكتبة Azure IoT SDK

قم بتثبيت مكتبة SDK لجهاز azure-iot على جهاز التطوير الخاص بك قبل استدعاء أي تعليمات برمجية ذات صلة:

pip install azure-iot-device

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

تتضمن فئة IoTHubDeviceClient أساليب لإنشاء اتصال متزامن من جهاز إلى Azure IoT Hub وتلقي الرسائل من IoT Hub.
تتضمن فئة IoTHubRegistryManager واجهات برمجة التطبيقات لعمليات IoT Hub Registry Manager. في هذه المقالة، توضح الأساليب من هذه الفئة كيفية الاتصال ب IoT Hub وإرسال رسالة إلى جهاز.

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

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

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

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

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

from azure.iot.device import IoTHubDeviceClient

توصيل عميل الجهاز

إنشاء مثيل IoTHubDeviceClient، وتمرير سلسلة الاتصال IoT Hub إلى create_from_connection_string. يؤدي هذا إلى إنشاء اتصال من الجهاز إلى IoT Hub.

بدلا من ذلك، يمكنك الاتصال IoTHubDeviceClientبجهاز باستخدام إحدى هذه الطرق:

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

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

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

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

إنشاء وظيفة معالج الرسائل لمعالجة الرسائل الواردة إلى الجهاز.

في هذا المثال، 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 لتعيين أسلوب معالج الرسائل للكائنIoTHubDeviceClient.

في هذا المثال، يتم إرفاق أسلوب معالج الرسائل المسمى message_handler بالكائن IoTHubDeviceClient client . 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 إلى جهاز.

إرسال رسائل من السحابة إلى الجهاز

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

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

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

from azure.iot.hub import IoTHubRegistryManager

توصيل مدير تسجيل IoT Hub

إنشاء مثيل لكائن IoTHubRegistryManager الذي يتصل بمركز IoT، وتمرير سلسلة الاتصال IoT Hub إلى from_connection_string.

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

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

استخدم 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

send_message.py - يوضح كيفية إرسال رسالة من سحابة إلى جهاز.

تثبيت حزم المراسلة Node.js

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

npm install azure-iot-device --save
npm install azure-iothub --save

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

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

تلقي الرسائل في تطبيق الجهاز

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

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

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

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

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

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

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

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

لمزيد من المعلومات حول الاختلافات بين دعم 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.

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

إضافة سلسلة IoT Hub وبروتوكول النقل

اتصل منConnectionString لإنشاء اتصال مركز من جهاز إلى IoT باستخدام هذه المعلمات:

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

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

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

إرسال رسائل من السحابة إلى الجهاز

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

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

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

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

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

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

إنشاء العميل باستخدام fromConnectionString باستخدام هذه المعلمات:

سلسلة اتصال مركز إنترنت الأشياء
نوع النقل

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

var connectionString = '{IoT Hub 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);

إنشاء رسالة

يتضمن كائن الرسالة الرسالة غير المتزامنة من سحابة إلى جهاز. تعمل وظيفة الرسالة بنفس الطريقة عبر 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";

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

يجب أن تتضمن كل رسالة لتلقي ملاحظات الرسالة قيمة لخاصية 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

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

نهج إعادة الاتصال

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

وقت استبقاء الرسائل ومحاولات إعادة المحاولة والحد الأقصى لعدد التسليم

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

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

مشاركة عبر

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

نظرة عامة

فهم قائمة انتظار الرسائل

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

الإعلان عن كائن DeviceClient

توفير معلمات الاتصال

الاستقصاء

أسلوب CompleteAsync

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

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

رد الاتصال

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

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

إرسال رسائل من السحابة إلى الجهاز

الإعلان عن كائن ServiceClient

توفير سلسلة الاتصال

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

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

إنشاء كائن feedbackReceiver

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

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

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

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

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

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

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

الإعلان عن كائن DeviceClient

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

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

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

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

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

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

إرسال رسائل من السحابة إلى الجهاز

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

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

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

إنشاء كائن ServiceClient

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

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

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

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

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

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

تثبيت مكتبة Azure IoT SDK

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

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

توصيل عميل الجهاز

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

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

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

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

إرسال رسائل من السحابة إلى الجهاز

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

توصيل مدير تسجيل IoT Hub

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

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

تثبيت حزم المراسلة Node.js

تلقي الرسائل في تطبيق الجهاز

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

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

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

AMQP وHTTP

MQTT

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

إضافة سلسلة IoT Hub وبروتوكول النقل

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

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

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

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

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

إرسال رسائل من السحابة إلى الجهاز

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

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

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

إنشاء رسالة

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

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

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