البرنامج التعليمي: استخدام واجهة برمجة تطبيقات 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 وإنشاء الرموز المميزة للحامل التي تستخدمها بعض واجهات برمجة تطبيقات REST للتخويل.
استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.
إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.
إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.
عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.
يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.
تخويل واجهة برمجة تطبيقات REST
قبل أن تتمكن من استخدام واجهة برمجة تطبيقات REST، يجب تكوين التخويل. تستخدم استدعاءات واجهة برمجة تطبيقات REST في هذا البرنامج التعليمي أحد نوعي التخويل:
- رمز حامل يخول الوصول إلى
https://apps.azureiotcentral.com. يمكنك استخدام هذا الرمز المميز للحامل لإنشاء رموز API المميزة في تطبيق IoT Central. - الرموز المميزة لواجهة برمجة تطبيقات المسؤول والمشغل التي تخول الوصول إلى القدرات في تطبيق IoT Central. يمكنك استخدام هذه الرموز المميزة لمعظم استدعاءات واجهة برمجة التطبيقات في هذا البرنامج التعليمي. تسمح هذه الرموز المميزة بالوصول إلى تطبيق IoT Central واحد محدد فقط.
قم بتشغيل أوامر Azure CLI التالية لإنشاء رمز مميز للحامل يخول الوصول إلى https://apps.azureiotcentral.com:
az account get-access-token --resource https://apps.azureiotcentral.com
تلميح
إذا بدأت مثيلا جديدا من shell الخاص بك، فقم بتشغيل az login مرة أخرى.
دون قيمة accessToken ، يمكنك استخدامها لاحقا في البرنامج التعليمي.
إشعار
تنتهي صلاحية الرموز المميزة للحامل بعد ساعة. إذا انتهت صلاحيتها، فقم بتشغيل نفس الأوامر لإنشاء رموز حامل جديدة.
إنشاء مجموعة موارد
استخدم Azure cli لإنشاء مجموعة موارد تحتوي على تطبيق IoT Central الذي تقوم بإنشائه في هذا البرنامج التعليمي:
az group create --name iot-central-rest-tutorial --location eastus
إنشاء تطبيق IoT Central
استخدم الأمر التالي لإنشاء تطبيق IoT Central باسم عشوائي لاستخدامه في هذا البرنامج التعليمي:
appName=app-rest-$(date +%s)
az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName
دون ملاحظة عن اسم التطبيق، يمكنك استخدامه لاحقا في هذا البرنامج التعليمي.
إنشاء رموز API المميزة
استخدم طلبات مستوى البيانات التالية لإنشاء رموز API المميزة للتطبيق في تطبيق IoT Central. تتطلب بعض الطلبات في هذا البرنامج التعليمي رمزا مميزا لواجهة برمجة التطبيقات مع أذونات المسؤول، ولكن يمكن للغالبية استخدام أذونات عامل التشغيل:
لإنشاء رمز مميز لعامل التشغيل يسمى operator-token باستخدام Azure CLI، قم بتشغيل الأمر التالي. المعرف الفريد العمومي للدور هو معرف دور عامل التشغيل في جميع تطبيقات IoT Central:
appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>
az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'
دون ملاحظة عن الرمز المميز للمشغل الذي يرجعه الأمر، ويمكنك استخدامه لاحقا في البرنامج التعليمي. يبدو الرمز المميز مثل SharedAccessSignature sr=2....
لإنشاء رمز مميز للمسؤول يسمى admin-token باستخدام Azure CLI، قم بتشغيل الأمر التالي. المعرف الفريد العمومي للدور هو معرف دور المسؤول في جميع تطبيقات IoT Central:
$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>
az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'
دون ملاحظة عن الرمز المميز للمسؤول الذي يرجعه الأمر، ويمكنك استخدامه لاحقا في البرنامج التعليمي. يبدو الرمز المميز مثل SharedAccessSignature sr=2....
إذا كنت ترغب في رؤية هذه الرموز المميزة في تطبيق IoT المركزي، فافتح التطبيق وانتقل إلى رموز واجهة برمجة التطبيقات لأذونات > الأمان>.
تسجيل جهاز
يجب عليك تسجيل جهاز مع IoT Central قبل أن يتمكن من الاتصال. استخدم الطلبات التالية لتسجيل جهازك في التطبيق الخاص بك واسترداد بيانات اعتماد الجهاز. ينشئ الطلب الأول جهازا مع الهاتف-001 كمعرف الجهاز:
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'
az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
دون ملاحظة عن idScope قيمتي و primaryKey التي يرجعها الأمر، ويمكنك استخدامها لاحقا في البرنامج التعليمي.
توفير جهاز وتوصيله
لتجنب الحاجة إلى إدخال بيانات اعتماد الجهاز يدويا على هاتفك الذكي، يمكنك استخدام رمز الاستجابة السريعة الذي تم إنشاؤه بواسطة IoT central. ترميز التعليمات البرمجية ل QR معرف الجهاز ونطاق المعرف والمفتاح الأساسي. لعرض رمز الاستجابة السريعة:
- افتح تطبيق IoT central الخاص بك باستخدام عنوان URL للتطبيق الذي قمت بتدوينه مسبقا.
- في تطبيق IoT Central، انتقل إلى Devices > My phone app > Connect > QR code. اترك هذه الصفحة مفتوحة حتى يتم توصيل الجهاز.
لتبسيط الإعداد، تستخدم هذه المقالة تطبيق الهاتف الذكي IoT أجهزة التوصيل و التشغيل كجهاز IoT. يرسل التطبيق بيانات تتبع الاستخدام التي تم جمعها من مستشعرات الهاتف الذكي، ويستجيب للأوامر التي تم استدعاؤها من IoT Central، ويبلغ عن قيم الخصائص إلى IoT Central.
قم بتثبيت التطبيق على هاتفك الذكي من أحد متاجر التطبيقات:
لتوصيل تطبيق IoT أجهزة التوصيل و التشغيل بتطبيق Iot Central الخاص بك:
افتح تطبيق IoT PnP على هاتفك الذكي.
في صفحة الترحيب، حدد مسح رمز الاستجابة السريعة. أشر بكاميرا الهاتف الذكي إلى رمز الاستجابة السريعة. ثم انتظر لبضع ثوان أثناء تأسيس الاتصال.
في صفحة القياس عن بعد في التطبيق، يمكنك مشاهدة البيانات التي يرسلها التطبيق إلى IoT Central. في صفحة السجلات، يمكنك مشاهدة الجهاز يتصل والعديد من رسائل التهيئة.
للتحقق من توفير الجهاز الآن، يمكنك استخدام واجهة برمجة تطبيقات REST:
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
دون القيمة التي template يرجعها الأمر، ويمكنك استخدامها لاحقا في البرنامج التعليمي.
يمكنك استخدام واجهة برمجة تطبيقات REST لإدارة قوالب الأجهزة في التطبيق. على سبيل المثال، لعرض قوالب الجهاز في التطبيق:
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
الاستعلام عن الجهاز والتحكم فيه
يمكنك استخدام واجهة برمجة تطبيقات REST للاستعلام عن بيانات تتبع الاستخدام من أجهزتك. يرجع الطلب التالي بيانات مقياس التسارع من جميع الأجهزة التي تشترك في معرف قالب جهاز معين:
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query
az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"
يمكنك استخدام واجهة برمجة تطبيقات REST لقراءة خصائص الجهاز وتعيينها. يقوم الطلب التالي بإرجاع كافة قيم الخصائص من مكون معلومات الجهاز الذي ينفذه الجهاز:
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
يمكنك استخدام واجهة برمجة تطبيقات REST لاستدعاء أوامر الجهاز. يستدعي الطلب التالي أمرا يقوم بتشغيل ضوء هاتفك الذكي مرتين لمدة ثلاث ثوان. لتشغيل الأمر، يجب أن تكون شاشة هاتفك الذكي قيد التشغيل مع ظهور تطبيق IoT أجهزة التوصيل و التشغيل:
appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'
تنظيف الموارد
إذا انتهيت من تطبيق IoT Central الذي استخدمته في هذا البرنامج التعليمي، يمكنك حذفه:
appName=<the app name generated previously>
az iot central app delete --name $appName --resource-group iot-central-rest-tutorial