البرنامج التعليمي: استخدام واجهة برمجة تطبيقات REST لإدارة تطبيق Azure IoT Central

  • مقالة

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

في هذا البرنامج التعليمي، تتعلم كيفية:

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

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

لإكمال الخطوات في هذا البرنامج التعليمي، تحتاج إلى:

  • اشتراك Azure نشط. في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

  • هاتف ذكي يعمل بنظام Android أو iOS يمكنك تثبيت تطبيق مجاني عليه من أحد متاجر التطبيقات الرسمية.

Azure CLI

يمكنك استخدام Azure CLI لإنشاء الرموز المميزة للحامل التي تستخدمها بعض واجهات برمجة تطبيقات REST للتخويل.

ساعي البريد

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

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

استيراد مجموعة Postman

لاستيراد المجموعة، افتح Postman وحدد Import. في مربع الحوار استيراد، حدد ارتباط ولصق في عنوان URL التالي، وحدد متابعة.

تحتوي مساحة العمل الآن على مجموعة البرامج التعليمية ل IoT Central REST. تتضمن هذه المجموعة جميع واجهات برمجة التطبيقات التي تستخدمها في البرنامج التعليمي.

تستخدم المجموعة متغيرات لتحديد معلمات استدعاءات واجهة برمجة تطبيقات REST. لمشاهدة المتغيرات، حدد ... بجوار البرنامج التعليمي IoT Central REST وحدد Edit. ثم حدد المتغيرات. يتم تعيين العديد من المتغيرات تلقائيا أثناء إجراء استدعاءات واجهة برمجة التطبيقات أو يكون لها قيم محددة مسبقا.

تخويل واجهة برمجة تطبيقات REST

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

  • رمز حامل يخول الوصول إلى https://management.azure.com. يمكنك استخدام هذا الرمز المميز للحامل عند إنشاء وحذف تطبيق IoT Central. تطبيق IoT Central هو مورد Azure.
  • رمز حامل يخول الوصول إلى https://apps.azureiotcentral.com. يمكنك استخدام هذا الرمز المميز للحامل لإنشاء رموز API المميزة في تطبيق IoT Central.
  • مسؤول رمز API المميز للمشغل وواجهة برمجة التطبيقات التي تخول الوصول إلى القدرات في تطبيق IoT Central الخاص بك. يمكنك استخدام هذه الرموز المميزة لمعظم استدعاءات واجهة برمجة التطبيقات في هذا البرنامج التعليمي. تسمح هذه الرموز المميزة بالوصول إلى تطبيق IoT Central واحد محدد فقط.

تعيين قيم للمتغيرات التالية في مجموعة Postman:

  • bearerToken: قم بتشغيل أوامر Azure CLI التالية لإنشاء رمز حامل يخول الوصول إلى https://management.azure.com:

    az login
az account get-access-token --resource https://management.azure.com

    تلميح

    قد تحتاج إلى التشغيل az login حتى إذا كنت تستخدم Cloud Shell.

    انسخ accessToken القيمة إلى عمود القيمة الحالية ل bearerToken في متغيرات المجموعة.

  • bearerTokenApp: قم بتشغيل أوامر Azure CLI التالية لإنشاء رمز حامل يخول الوصول إلى https://apps.azureiotcentral.com:

    az account get-access-token --resource https://apps.azureiotcentral.com

    تلميح

    إذا بدأت مثيلا جديدا من shell الخاص بك، فقم بتشغيل az login مرة أخرى.

    انسخ accessToken القيمة إلى عمود القيمة الحالية ل bearerTokenApp في متغيرات المجموعة.

  • subscriptionId: تم تضمين معرف الاشتراك الخاص بك في الإخراج من الأمرين السابقين. انسخ subscription القيمة إلى عمود القيمة الحالية لمعرف الاشتراك في متغيرات المجموعة.

Screenshot that shows the variables set manually in the Postman collection.

تأكد من حفظ التغييرات إلى مجموعة Postman.

إشعار

تنتهي صلاحية الرموز المميزة للحامل بعد ساعة.

إنشاء تطبيق

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

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب إنشاء تطبيق مركزي ل IoT.
  2. حدد إرسال.
  3. تحقق من نجاح الطلب. إذا فشل، تحقق من إدخال قيم متغير bearerToken و subscriptionId في مجموعة Postman.
  4. حدد Visualize لمشاهدة عنوان URL لتطبيق IoT Central الجديد. دون ملاحظة عن عنوان URL هذا، فأنت بحاجة إليه لاحقا في هذا البرنامج التعليمي.

Screenshot that shows the Visualize tab with the application URL in Postman.

إنشاء رموز API المميزة

استخدم طلبات مستوى البيانات التالية لإنشاء رموز API المميزة للتطبيق في تطبيق IoT Central. تتطلب بعض الطلبات في هذا البرنامج التعليمي رمزا مميزا لواجهة برمجة التطبيقات مع أذونات المسؤول، ولكن يمكن للغالبية استخدام أذونات عامل التشغيل:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب إنشاء رمز مميز للمشغل.
  2. حدد إرسال.
  3. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب إنشاء رمز مميز للمسؤول.
  4. حدد إرسال.

إذا كنت ترغب في رؤية هذه الرموز المميزة في تطبيق IoT المركزي، فافتح التطبيق وانتقل إلى رموز واجهة برمجة التطبيقات لأذونات > الأمان>.

إشعار

يضيف البرنامج النصي في Postman تلقائيا رموز API المميزة هذه إلى قائمة متغيرات المجموعة نيابة عنك.

تسجيل جهاز

يجب عليك تسجيل جهاز مع IoT Central قبل أن يتمكن من الاتصال. استخدم الطلبات التالية لتسجيل جهازك في التطبيق الخاص بك واسترداد بيانات اعتماد الجهاز. ينشئ الطلب الأول جهازا مع الهاتف-001 كمعرف الجهاز:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب إضافة جهاز.
  2. حدد إرسال. في الاستجابة، لاحظ أن الجهاز غير مزود.
  3. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب الحصول على بيانات اعتماد الجهاز.
  4. حدد إرسال.
  5. تعرض علامة التبويب Visualize قيم ID Scope و Primary key التي يحتاج الجهاز إلى توصيلها.

توفير جهاز وتوصيله

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

  1. افتح تطبيق IoT central الخاص بك باستخدام عنوان URL للتطبيق الذي قمت بتدوينه مسبقا.
  2. في تطبيق IoT Central، انتقل إلى Devices > My phone app > الاتصال > رمز الاستجابة السريعة. اترك هذه الصفحة مفتوحة حتى يتم توصيل الجهاز.

Screenshot that shows the QR code you use to connect the device.

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

قم بتثبيت التطبيق على هاتفك الذكي من أحد متاجر التطبيقات:

Get the app for your Android phone on Google Play.Download the app for your phone from the App Store.

لتوصيل تطبيق IoT أجهزة التوصيل و التشغيل بتطبيق Iot Central الخاص بك:

  1. افتح تطبيق IoT PnP على هاتفك الذكي.

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

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

للتحقق من توفير الجهاز الآن، يمكنك استخدام واجهة برمجة تطبيقات REST:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب الحصول على جهاز.
  2. حدد إرسال. في الاستجابة، لاحظ أن الجهاز تم توفيره الآن. كما عين IoT Central قالب جهاز للجهاز استنادا إلى معرف النموذج المرسل من قبل الجهاز.

يمكنك استخدام واجهة برمجة تطبيقات REST لإدارة قوالب الأجهزة في التطبيق. على سبيل المثال، لعرض قوالب الجهاز في التطبيق:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب List device templates.
  2. حدد إرسال.

الاستعلام عن الجهاز والتحكم فيه

يمكنك استخدام واجهة برمجة تطبيقات REST للاستعلام عن بيانات تتبع الاستخدام من أجهزتك. يرجع الطلب التالي بيانات مقياس التسارع من جميع الأجهزة التي تشترك في معرف قالب جهاز معين:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب تشغيل استعلام.
  2. حدد إرسال.

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

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد الحصول على خصائص من طلب مكون.
  2. حدد إرسال.

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

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب أمر الاتصال.
  2. حدد إرسال.

تصدير القياس عن بعد

يمكنك استخدام واجهة برمجة تطبيقات REST لتكوين وإدارة تطبيق IoT Central. توضح لك الخطوات التالية كيفية تكوين تصدير البيانات لإرسال قيم بيانات تتبع الاستخدام إلى إخطار على الويب. لتبسيط الإعداد، تستخدم هذه المقالة خطاف ويب RequestBin كوجهة. RequestBin هي خدمة غير تابعة ل Microsoft.

لإنشاء نقطة نهاية الاختبار لوجهة تصدير البيانات:

  1. انتقل إلى RequestBin.
  2. حدد Create a RequestBin.
  3. سجل الدخول باستخدام إحدى الطرق المتوفرة.
  4. انسخ عنوان URL لنقطة نهاية RequestBin.
  5. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST وانتقل إلى متغيرات المجموعة.
  6. الصق عنوان URL لنقطة نهاية RequestBin في عمود القيمة الحالية ل webHookURL في متغيرات المجموعة.
  7. ا‏‏حفظ التغييرات.

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

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب إنشاء وجهة تصدير خطاف الويب.
  2. حدد إرسال.

لتكوين تعريف التصدير في تطبيق IoT Central باستخدام واجهة برمجة تطبيقات REST:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب إنشاء تعريف تصدير بيانات تتبع الاستخدام.
  2. حدد إرسال. لاحظ أن الحالة لم تبدأ.

قد يستغرق الأمر بضع دقائق لبدء التصدير. للتحقق من حالة التصدير باستخدام واجهة برمجة تطبيقات REST:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب Get an export by ID.
  2. حدد إرسال. عندما تكون الحالة سليمة، يرسل IoT Central بيانات تتبع الاستخدام إلى خطاف الويب الخاص بك.

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

عندما يرسل تطبيق هاتفك الذكي بيانات تتبع الاستخدام، انتقل إلى RequestBin لعرض بيانات تتبع الاستخدام التي تم تصديرها.

تنظيف الموارد

إذا انتهيت من تطبيق IoT Central الذي استخدمته في هذا البرنامج التعليمي، يمكنك استخدام واجهة برمجة تطبيقات REST لحذفه:

  1. في Postman، افتح مجموعة البرامج التعليمية ل IoT Central REST، وحدد طلب حذف تطبيق IoT المركزي.
  2. حدد إرسال.

تلميح

يستخدم هذا الطلب رمزا مميزا للحامل أنشأته في بداية البرنامج التعليمي. تنتهي صلاحية الرموز المميزة للحامل بعد ساعة. قد تحتاج إلى إنشاء رمز حامل جديد يخول الوصول إلى https://apps.azureiotcentral.com.

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

إذا كنت تفضل الاستمرار في مجموعة من الدروس IoT المركزية ومعرفة المزيد عن بناء حل IoT المركزية، فانظر:

إنشاء قالب جهاز بوابة