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

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

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

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

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

إشعار

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

توضح لك هذه المقالة كيفية تطوير نوعين من التطبيقات:

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

إشعار

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

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

• مركز IoT. تتطلب بعض استدعاءات SDK سلسلة الاتصال الأساسي ل IoT Hub، لذا دون ملاحظة عن سلسلة الاتصال.

• جهاز مسجل. تتطلب بعض استدعاءات SDK سلسلة الاتصال الأساسي للجهاز، لذا قم بتدوين سلسلة الاتصال.

• سلسلة الاتصال خدمة IoT Hub

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

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

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

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

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

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

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

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

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

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

• متطلبات لغة SDK:

  • .NET SDK - يتطلب Visual Studio.
  • يوصى باستخدام Python SDK - Python الإصدار 3.7 أو أحدث. تأكد من استخدام التثبيت 32 بت أو 64 بت كما هو مطلوب من قبل الإعداد الخاص بك. عند المطالبة في أثناء التثبيت، تأكد من إضافة Python إلى متغيرات البيئة الخاصة بالنظام الأساسي.
  • Java - يتطلب Java SE Development Kit 8. تأكد من تحديد Java 8 ضمن الدعم طويل المدى للانتقال إلى التنزيلات ل JDK 8.
  • Node.js - يتطلب Node.js الإصدار 10.0.x أو أحدث.

نظرة عامة

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

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

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

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

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

إضافة حزمة NuGet للجهاز

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

الاتصال بجهاز

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

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

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

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

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

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

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

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

نموذج جهاز SDK

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

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

تطبيق الواجهة الخلفية:

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

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

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

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

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

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

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

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

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{IoT hub service connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عينة خدمة SDK

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

نظرة عامة

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

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

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

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

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

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

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

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

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

الاتصال بالجهاز

للاتصال بجهاز:

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

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

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

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

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

   client.open(true);
   

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

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

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

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

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

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

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

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

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

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

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

TwinCollection reportedProperties = twin.getReportedProperties();

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

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

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

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

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

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

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

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

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

نموذج جهاز SDK

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

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

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

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

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

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

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

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

الاتصال بعميل خدمة مركز IoT

للاتصال ب IoT Hub لعرض معلومات الجهاز المزدوج وتحديثها:

1. إنشاء كائن DeviceTwinClientOptions . قم بتعيين أي خيارات مطلوبة للتطبيق الخاص بك. يتم تمرير هذه الخيارات إلى DeviceTwin الكائن .
2. استخدم منشئ DeviceTwin لإنشاء الاتصال بمركز IoT. DeviceTwin يعالج الكائن الاتصال مع مركز IoT الخاص بك. كمعلمات، قم بتوفير خدمة IoT Hub سلسلة الاتصال التي قمت بإنشائها في قسم المتطلبات الأساسية والعنصرDeviceTwinClientOptions.
3. يمثل كائن DeviceTwinDevice توأم الجهاز بخصائصه وعلاماته.

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

public static final String iotHubConnectionString = "{IoT hub service connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عينة خدمة SDK

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

نظرة عامة

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

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

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

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

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

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

الاتصال بجهاز

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

لتوصيل تطبيق بجهاز:

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

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IOT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عينات جهاز SDK

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

print()

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

print()

عينة خدمة SDK

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

نظرة عامة

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

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

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

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

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

تثبيت حزم SDK

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

npm install azure-iot-device --save

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

npm install azure-iothub --save

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

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

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

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Iot Hub service connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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