بدء استخدام توائم الجهاز (Python)

• المبادره القطريه
• NET.
• Python
• Node.js
• Java

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

إشعار

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

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

• خزّن بيانات التعريف للجهاز من النهاية الخلفية للحل الخاص بك.

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

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

• الاستعلام عن بيانات التعريف للجهاز، أو التكوين، أو الحالة.

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

تخزن مراكز IoT توائم الجهاز، والتي تحتوي على العناصر التالية:

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

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

• الخصائص المبلغ عنها. عناصر JSON قابلة للتعديل من خلال تطبيق الجهاز ويمكن قراءتها بواسطة النهاية الخلفية للحل.

لا يمكن أن تحتوي العلامات والخصائص على صفائف، ولكن يمكن أن تحتوي على كائنات متداخلة.

يوضح الرسم التوضيحي التالي تنظيم توأم الجهاز:

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

توضح لك هذه المقالة كيفية:

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

• استعلم عن الأجهزة من تطبيقك الخلفي باستخدام عوامل تصفية على العلامات والخصائص التي تم إنشاؤها مسبقًا.

في هذه المقالة، يمكنك إنشاء تطبيقي وحدة تحكم Python:

• AddTagsAndQuery: تطبيق للجهة الخلفية يضيف علامات واستعلامات توائم الجهاز.

• ReportConnectivity: تطبيق جهاز محاكاة يتصل بمركز IoT ويبلغ عن حالة الاتصال.

إشعار

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

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

• حساب Azureنشط. (إذا لم يكن لديك حساب، يمكنك إنشاء حساب مجاني خلال دقيقتين فقط.)

• IoT Hub. أنشئ واحدا باستخدام CLI أو مدخل Microsoft Azure.

• جهاز مسجل. سجَل واحدًا في مدخل Azure.

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

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

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

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

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

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

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

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

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

   

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

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

   

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

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

في هذا القسم، تقوم بإنشاء تطبيق وحدة التحكم في Python الذي يضيف بيانات التعريف للموقع إلى توأم الجهاز المرتبط بـ {Device ID}. يستعلم التطبيق عن مركز IoT للأجهزة الموجودة في الولايات المتحدة، ثم عن الأجهزة التي تبلغ عن اتصال شبكة خلوية.

1. في دليل العمل، افتح موجه الأوامر وقم بتثبيت Azure IoT Hub Service SDK for Python.

   pip install azure-iot-hub
   

2. باستخدام محرر نصوص، قم بإنشاء ملف AddTagsAndQuery.py جديد.

3. أضف التعليمة البرمجية التالية لاستيراد الوحدات المطلوبة من SDK للخدمة:

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

4. أضف التعليمات البرمجية التالية. استبدل [IoTHub Connection String] بسلسلة اتصال IoT hub التي نسختها في الحصول على سلسلة اتصال IoT hub. استبدل [Device Id] بمعرف الجهاز (الاسم) من جهازك المسجل في مركز IoT.

   IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
   DEVICE_ID = "[Device Id]"
   

5. أضف التعليمات البرمجية التالية إلى ملف AddTagsAndQuery.py:

   def iothub_service_sample_run():
       try:
           iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)
   
           new_tags = {
                   'location' : {
                       'region' : 'US',
                       'plant' : 'Redmond43'
                   }
               }
   
           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)
   
           # Add a delay to account for any latency before executing the query
           sleep(1)
   
           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])))
   
       except Exception as ex:
           print("Unexpected error {0}".format(ex))
           return
       except KeyboardInterrupt:
           print("IoT Hub Device Twin service sample stopped")
   

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

6. أضف التعليمة البرمجية التالية في نهاية AddTagsAndQuery.py لتنفيذ وظيفة iothub_service_sample_run:

   if __name__ == '__main__':
       print("Starting the Python IoT Hub Device Twin service sample...")
       print()
   
       iothub_service_sample_run()
   

7. قم بتشغيل التطبيق باستخدام:

   python AddTagsAndQuery.py
   

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

   

إنشاء تطبيق جهاز يقوم بتحديث الخصائص المبلغ عنها

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

1. من موجه الأوامر في دليل العمل الخاص بك، قم بتثبيت Azure IoT Hub Device SDK for Python:

   pip install azure-iot-device
   

2. باستخدام محرر نصوص، قم بإنشاء ملف ReportConnectivity.py جديد.

3. أضف التعلمية البرمجية التالية لاستيراد الوحدات المطلوبة من SDK للجهاز:

   import time
   from azure.iot.device import IoTHubModuleClient
   

4. أضف التعليمات البرمجية التالية. استبدل قيمة العنصر النائب [IoTHub Device Connection String] بسلسلة اتصال الجهاز التي وجدتها أثناء تسجيل جهاز جديد في مركز IoT:

   CONNECTION_STRING = "[IoTHub Device Connection String]"
   

5. أضف التعليمة البرمجية التالية إلى ملف ReportConnectivity.py لإنشاء مثيل للعميل وتنفيذ وظيفة توائم الجهاز:

   def create_client():
       # Instantiate client
       client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)
   
       # Define behavior for receiving twin desired property patches
       def twin_patch_handler(twin_patch):
           print("Twin patch received:")
           print(twin_patch)
   
       try:
           # Set handlers on the client
           client.on_twin_desired_properties_patch_received = twin_patch_handler
       except:
           # Clean up in the event of failure
           client.shutdown()
   
       return client
   

6. أضف التعليمة البرمجية التالية في نهاية ReportConnectivity.py لتشغيل التطبيق:

   def main():
       print ( "Starting the Python IoT Hub Device Twin device sample..." )
       client = create_client()
       print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )
   
       try:
           # Update reported properties with cellular information
           print ( "Sending data as reported property..." )
           reported_patch = {"connectivity": "cellular"}
           client.patch_twin_reported_properties(reported_patch)
           print ( "Reported properties updated" )
   
           # Wait for program exit
           while True:
               time.sleep(1000000)
       except KeyboardInterrupt:
           print ("IoT Hub Device Twin device sample stopped")
       finally:
           # Graceful exit
           print("Shutting down IoT Hub Client")
           client.shutdown()
   
   if __name__ == '__main__':
       main()
   

7. قم بتشغيل تطبيق الجهاز:

   python ReportConnectivity.py
   

   يجب أن ترى تأكيدًا على تحديث خصائص توأم الجهاز التي تم الإبلاغ عنها.

   

8. الآن بعد أن أبلغ الجهاز عن معلومات الاتصال الخاصة به، يجب أن تظهر في كلا الاستعلامين. ارجع وقم بتشغيل الاستعلامات مرة أخرى:

   python AddTagsAndQuery.py
   

   هذه المرة من المفترض أن يظهر {Device ID} في نتائج كلا الاستعلامين.

   

   في تطبيق جهازك، سترى تأكيدًا على استلام التصحيح المزدوج للخصائص المطلوبة بواسطة تطبيق الخدمة.

   

في هذه المقالة، ستتمكن من:

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

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

‏‫تعّرف على كيفية:

• إرسال بيانات تتبع الاستخدام من الأجهزة، راجع مقالة تشغيل سريع: إرسال بيانات تتبع الاستخدام من جهاز IoT Plug and Play إلى Azure IoT Hub.

• تكوين الأجهزة باستخدام الخصائص المطلوبة لتوأم الجهاز، راجع البرنامج التعليمي: تكوين أجهزتك من خدمة خلفية.

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