استكشاف الأخطاء وإصلاحها في Azure IoT Central
تتضمن هذه المقالة إرشادات استكشاف الأخطاء وإصلاحها لمشكلات اتصال الجهاز ومشكلات تكوين تصدير البيانات في تطبيقات IoT Central.
مشكلات اتصال الجهاز
يساعدك هذا القسم على تحديد ما إذا كانت بياناتك تصل إلى IoT Central.
إذا لم تكن قد فعلت ذلك بالفعل، فقم بتثبيت az cli الأداة والملحق azure-iot .
لمعرفة كيفية تثبيت az cli، راجع تثبيت Azure CLI.
لتثبيت الملحقazure-iot، قم بتشغيل الأمر التالي:
az extension add --name azure-iot
إشعار
قد تتم مطالبتك بتثبيت المكتبة في uamqp المرة الأولى التي تقوم فيها بتشغيل أمر ملحق.
عند تثبيت الملحق azure-iot ، ابدأ تشغيل جهازك لمعرفة ما إذا كانت الرسائل التي يرسلها تشق طريقها إلى IoT Central.
استخدم الأوامر التالية لتسجيل الدخول إلى الاشتراك حيث يكون لديك تطبيق IoT Central الخاص بك:
az login
az account set --subscription <your-subscription-id>
لمراقبة بيانات تتبع الاستخدام التي يرسلها جهازك، استخدم الأمر التالي:
az iot central diagnostics monitor-events --app-id <iot-central-app-id> --device-id <device-name>
إذا كان الجهاز متصلا بنجاح ب IoT Central، فسترى إخراجا مشابها للمثال التالي:
Monitoring telemetry.
Filtering on device: device-001
{
"event": {
"origin": "device-001",
"module": "",
"interface": "",
"component": "",
"payload": {
"temp": 65.57910343679293,
"humid": 36.16224660107426
}
}
}
لمراقبة تحديثات الخاصية التي يتبادلها جهازك مع IoT Central، استخدم أمر المعاينة التالي:
az iot central diagnostics monitor-properties --app-id <iot-central-app-id> --device-id <device-name>
إذا كان الجهاز يرسل تحديثات الخصائص بنجاح، فسترى إخراجا مشابها للمثال التالي:
Changes in reported properties:
version : 32
{'state': 'true', 'name': {'value': {'value': 'Contoso'}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac
': 200}, 'brightness': {'value': {'value': 2}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac': 200}, 'p
rocessorArchitecture': 'ARM', 'swVersion': '1.0.0'}
إذا رأيت البيانات تظهر في المحطة الطرفية الخاصة بك، فإن البيانات تجعلها بقدر تطبيق IoT Central الخاص بك.
إذا لم تظهر أي بيانات بعد بضع دقائق، فحاول الضغط Enter على المفتاح أو return على لوحة المفاتيح، في حالة توقف الإخراج.
إذا كنت لا تزال لا ترى أي بيانات تظهر على المحطة الطرفية، فمن المحتمل أن جهازك لديه مشكلات في اتصال الشبكة، أو أنه لا يرسل البيانات بشكل صحيح إلى IoT Central.
التحقق من حالة التوفير لجهازك
إذا لم تظهر بياناتك في شاشة CLI، فتحقق من حالة التوفير لجهازك عن طريق تشغيل الأمر التالي:
az iot central device registration-info --app-id <iot-central-app-id> --device-id <device-name>
يظهر الإخراج التالي مثالا لجهاز تم حظره من الاتصال:
{
"@device_id": "v22upeoqx6",
"device_registration_info": {
"device_status": "blocked",
"display_name": "Environmental Sensor - v22upeoqx6",
"id": "v22upeoqx6",
"instance_of": "urn:krhsi_k0u:modelDefinition:w53jukkazs",
"simulated": false
},
"dps_state": {
"error": "Device is blocked from connecting to IoT Central application. Unblock the device in IoT Central and retry. Learn more:
https://aka.ms/iotcentral-docs-dps-SAS",
"status": null
}
}
| حالة توفير الجهاز | الوصف | التخفيف المحتمل |
|---|---|---|
| توفير | لا توجد مشكلة يمكن التعرف عليها على الفور. | غير متوفر |
| مسجلة | لم يتصل الجهاز بعد ب IoT Central. | تحقق من سجلات جهازك بحثا عن مشكلات في الاتصال. |
| محظور | تم حظر الجهاز من الاتصال ب IoT Central. | تم حظر الجهاز من الاتصال بتطبيق IoT Central. قم بإلغاء حظر الجهاز في IoT Central وأعد المحاولة. لمعرفة المزيد، راجع قيم حالة الجهاز. |
| غير معتمد | الجهاز غير معتمد. | لم تتم الموافقة على الجهاز للاتصال بتطبيق IoT Central. الموافقة على الجهاز في IoT Central وإعادة المحاولة. لمعرفة المزيد، راجع قيم حالة الجهاز |
| غير معين | لم يتم تعيين الجهاز إلى قالب جهاز. | قم بتعيين الجهاز إلى قالب جهاز حتى يعرف IoT Central كيفية تحليل البيانات. |
تعرف على المزيد حول قيم حالة الجهاز في قيم حالة واجهة المستخدم والجهاز في واجهة برمجة تطبيقات REST.
رموز الخطأ
إذا كنت لا تزال غير قادر على تشخيص سبب عدم ظهور بياناتك في monitor-events، فإن الخطوة التالية هي البحث عن رموز الخطأ التي أبلغ عنها جهازك.
ابدأ جلسة تصحيح الأخطاء على جهازك، أو اجمع السجلات من جهازك. تحقق من وجود أي رموز خطأ يبلغها الجهاز.
تعرض الجداول التالية رموز الخطأ الشائعة والإجراءات المحتملة للتخفيف منها.
إذا كنت ترى مشكلات تتعلق بتدفق المصادقة:
| رمز الخطأ | الوصف | التخفيف المحتمل من المخاطر |
|---|---|---|
| 400 | نص الطلب غير صالح. على سبيل المثال، لا يمكن تحليله، أو لا يمكن التحقق من صحة الكائن. | تأكد من إرسال نص الطلب الصحيح كجزء من تدفق التصديق، أو استخدام SDK للجهاز. |
| 401 | لا يمكن التحقق من صحة رمز التخويل المميز. على سبيل المثال، انتهت صلاحيتها أو لا تنطبق على URI الخاص بالطلب. يتم أيضا إرجاع رمز الخطأ هذا إلى الأجهزة كجزء من تدفق إثبات TPM. | تأكد من أن جهازك يحتوي على بيانات الاعتماد الصحيحة. |
| 404 | مثيل Device Provisioning Service أو مورد مثل التسجيل غير موجود. | تقديم تذكرة مع دعم العملاء. |
| 412 | ETag لا يتطابق في الطلب مع ETag المورد الموجود، وفقا RFC7232. |
تقديم تذكرة مع دعم العملاء. |
| 429 | الخدمة هي عمليات تقييد. للحصول على حدود خدمة معينة، راجع حدود خدمة توفير جهاز IoT Hub. | تقليل تكرار الرسائل، وتقسيم المسؤوليات بين المزيد من الأجهزة. |
| 500 | حدث خطأ داخلي. | قم بتقديم تذكرة مع دعم العملاء لمعرفة ما إذا كان يمكنهم مساعدتك بشكل أكبر. |
رموز خطأ التخويل التفصيلية
| خطأ | رمز الخطأ الفرعي | ملاحظات |
|---|---|---|
| 401 غير مصرح به | 401002 | يستخدم الجهاز بيانات اعتماد غير صالحة أو منتهية الصلاحية. يبلغ DPS عن هذا الخطأ. |
| 401 غير مصرح به | 400209 | إما أن الجهاز ينتظر الموافقة من قبل عامل تشغيل أو قام عامل تشغيل بحظره. |
| 401 IoTHubUnauthorized | يستخدم الجهاز رمز أمان منتهية الصلاحية. يبلغ IoT Hub عن هذا الخطأ. | |
| 401 IoTHubUnauthorized | DEVICE_DISABLED | تم تعطيل الجهاز في مركز IoT هذا وانتقل إلى مركز IoT آخر. إعادة توفير الجهاز. |
| 401 IoTHubUnauthorized | DEVICE_BLOCKED | قام عامل تشغيل بحظر هذا الجهاز. |
رموز خطأ تحميل الملف
فيما يلي قائمة برموز الأخطاء الشائعة التي قد تراها عندما يحاول جهاز تحميل ملف إلى السحابة. تذكر أنه قبل أن يتمكن جهازك من تحميل ملف، يجب تكوين تحميلات ملفات الجهاز في التطبيق الخاص بك.
| رمز الخطأ | الوصف | التخفيف المحتمل من المخاطر |
|---|---|---|
| 403006 | لقد تجاوزت عدد عمليات تحميل الملفات المتزامنة. الحد المسموح به لكل عميل جهاز هو 10 عمليات تحميل متزامنة للملفات. | تأكد من أن الجهاز يعلم IoT Central على الفور بأن عملية تحميل الملف قد اكتملت. إذا لم ينجح ذلك، فحاول تقليل مهلة الطلب. |
مشكلات البيانات غير المحذوزة
عندما تثبت أن جهازك يرسل البيانات إلى IoT Central، فإن الخطوة التالية هي التأكد من أن جهازك يرسل البيانات بتنسيق صالح.
للكشف عن الفئات التي تواجهها المشكلة، قم بتشغيل أمر Azure CLI الأنسب للسيناريو الخاص بك:
للتحقق من صحة بيانات تتبع الاستخدام، استخدم أمر المعاينة:
az iot central diagnostics validate-messages --app-id <iot-central-app-id> --device-id <device-name>للتحقق من صحة تحديثات الخصائص، استخدم أمر المعاينة:
az iot central diagnostics validate-properties --app-id <iot-central-app-id> --device-id <device-name>
قد تتم مطالبتك بتثبيت المكتبة uamqp في المرة الأولى التي تقوم فيها بتشغيل validate أمر.
الأنواع الثلاثة الشائعة للمشكلة التي تتسبب في عدم ظهور بيانات الجهاز في IoT Central هي:
- قالب الجهاز إلى عدم تطابق بيانات الجهاز.
- البيانات JSON غير صالحة.
- تتسبب الإصدارات القديمة من IoT Edge في عرض بيانات تتبع الاستخدام من المكونات بشكل غير صحيح كبيانات غير معروضة.
قالب الجهاز إلى عدم تطابق بيانات الجهاز
يجب أن يستخدم الجهاز نفس الاسم والغلاف كما هو مستخدم في قالب الجهاز لأي أسماء حقول بيانات تتبع الاستخدام في الحمولة التي يرسلها. يظهر الإخراج التالي مثالا لرسالة تحذير حيث يرسل الجهاز قيمة بيانات تتبع الاستخدام تسمى Temperature، عندما يجب أن يكون temperature:
Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[WARNING] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['Temperature']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.
يجب أن يستخدم الجهاز نفس الاسم والغلاف كما هو مستخدم في قالب الجهاز لأي أسماء خصائص في الحمولة التي يرسلها. يظهر الإخراج التالي مثالا لرسالة تحذير حيث لم يتم تعريف الخاصية osVersion في قالب الجهاز:
Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
[WARNING] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['osVersion']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.
يجب أن يستخدم الجهاز أنواع البيانات المعرفة في قالب الجهاز لأي بيانات تتبع الاستخدام أو قيم الخصائص. على سبيل المثال، ترى عدم تطابق مخطط إذا كان النوع المحدد في قالب الجهاز منطقيا، ولكن الجهاز يرسل سلسلة. يظهر الإخراج التالي مثالا لرسالة خطأ حيث يستخدم الجهاز قيمة سلسلة لخاصية تم تعريفها على أنها مزدوجة:
Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[ERROR] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Datatype of telemetry field 'temperature' does not match the datatype double. Data sent by the device : curr_temp. For more information, see: https://aka.ms/iotcentral-payloads
تقوم أوامر التحقق من الصحة أيضا بالإبلاغ عن خطأ إذا تم تعريف نفس اسم بيانات تتبع الاستخدام في واجهات متعددة، ولكن الجهاز ليس متوافقا مع IoT أجهزة التوصيل و التشغيل.
إذا كنت تفضل استخدام واجهة المستخدم الرسومية، فاستخدم طريقة عرض بيانات IoT Central Raw لمعرفة ما إذا كان هناك شيء ما لا يتم تصميمه.
عند اكتشاف المشكلة، قد تحتاج إلى تحديث البرنامج الثابت للجهاز، أو إنشاء قالب جهاز جديد يقوم بنمذجة البيانات التي لم يتم عرضها مسبقا.
إذا اخترت إنشاء قالب جديد يقوم بنمذجة البيانات بشكل صحيح، فبادر بترحيل الأجهزة من القالب القديم إلى القالب الجديد. لمعرفة المزيد، راجع إدارة الأجهزة في تطبيق Azure IoT Central.
JSON غير صالح
إذا لم يتم الإبلاغ عن أي أخطاء، ولكن لم تظهر قيمة، فمن المحتمل أن تكون JSON مشوهة في الحمولة التي يرسلها الجهاز. لمعرفة المزيد، راجع بيانات تتبع الاستخدام والخصائص وحمولة الأوامر.
لا يمكنك استخدام أوامر التحقق من الصحة أو طريقة عرض البيانات الأولية في واجهة المستخدم للكشف عن ما إذا كان الجهاز يرسل JSON مشوه.
إصدار IoT Edge
لعرض بيانات تتبع الاستخدام من المكونات المستضافة في وحدات IoT Edge بشكل صحيح، استخدم إصدار IoT Edge 1.2.4 أو أحدث. إذا كنت تستخدم إصدارا سابقا، فسيعرض القياس عن بعد من المكونات في وحدات IoT Edge ك _unmodeleddata.
مشكلات الهوية المدارة لتصدير البيانات
أنت تستخدم هوية مدارة لتخويل الاتصال بوجهة تصدير. لا تصل البيانات إلى وجهة التصدير.
قبل تكوين وجهة التصدير أو تمكينها، تأكد من إكمال الخطوات التالية:
تمكين الهوية المدارة لتطبيق IoT Central. للتحقق من تمكين الهوية المدارة، انتقل إلى صفحة الهوية للتطبيق الخاص بك في مدخل Microsoft Azure أو استخدم أمر CLI التالي:
az iot central app identity show --name {your app name} --resource-group {your resource group name}تكوين الأذونات للهوية المدارة. لعرض الأذونات المعينة، حدد تعيينات دور Azure في صفحة الهوية لتطبيقك في مدخل Microsoft Azure أو استخدم
az role assignment listالأمر CLI. الأذونات المطلوبة هي:الوجهة الإذن تخزين Azure Blob المساهم في بيانات مخزن البيانات الثنائية الكبيرة ناقل خدمة Azure مرسل بيانات ناقل خدمة Azure مراكز أحداث Azure مرسل بيانات مراكز أحداث Azure Event Hubs Azure Data Explorer (Kusto) مسؤول إذا لم يتم تعيين الأذونات بشكل صحيح قبل إنشاء الوجهة في تطبيق IoT Central، فحاول إزالة الوجهة ثم إضافتها مرة أخرى.
تكوين أي شبكات ظاهرية ونقاط نهاية خاصة ونهج جدار الحماية.
إشعار
إذا كنت تستخدم هوية مدارة لتخويل الاتصال بوجهة تصدير، فلن يقوم IoT Central بتصدير البيانات من أجهزة محاكاة.
لمعرفة المزيد، راجع تصدير البيانات.
مشكلات اتصال وجهة تصدير البيانات
تعرض صفحة تعريف التصدير معلومات حول الاتصالات الفاشلة بوجهة التصدير:
مشاكل البيانات المفقودة لتصدير البيانات
تصدير البيانات يصدر فقط البيانات التي تصل إلى التطبيق الخاص بك بعد تمكين تصدير البيانات. إذا كنت بحاجة إلى تصدير بيانات أو بيانات تاريخية لم يتم فقدانها أثناء إيقاف تصدير البيانات مؤقتا، يمكنك استخدام واجهة برمجة تطبيقات REST ل IoT Central للاستعلام عن بيانات تتبع استخدام الجهاز. استخدم استعلاما لاسترداد البيانات المفقودة ثم أضف البيانات إلى وجهة التصدير. لمعرفة المزيد، راجع كيفية استخدام واجهة برمجة تطبيقات IoT Central REST للاستعلام عن الأجهزة.
الخطوات التالية
إذا كنت بحاجة إلى مزيد من المساعدة، يمكنك الاتصال بخبراء Azure في منتديات Microsoft Q&A و Stack Overflow. بدلا من ذلك، يمكنك تقديم تذكرة دعم Azure.
لمزيد من المعلومات، راجع خيارات الدعم والمساعدة في Azure IoT.