بدء مسابقة المطوّرين لواجهات برمجة التطبيقات في Home استعرِض مهاراتك للحصول على فرصة الفوز بجوائز قيّمة.

تحديد مشاكل الدمج وحلّها

توفّر لك Google Cloud الأدوات اللازمة لمراقبة موثوقية مشاريعك باستخدام Google Cloud Monitoring وتحديد المشاكل وحلّها باستخدام سجلّات الأخطاء Google Cloud Logging. عند حدوث خطأ أثناء تنفيذ طلبات المستخدمين، يسجّل مسار بيانات Google Home Analytics هذا الخطأ في مقاييسك، وينشر سجلّ خطأ في سجلّات مشروعك.

هناك خطوتان لتحديد المشاكل وحلّها:

تتبُّع حالة مشاريعك باستخدام مقاييس المنزل الذكي
يمكنك التحقيق في المشاكل من خلال الاطّلاع على أوصاف الأخطاء التفصيلية في سجلّات الأخطاء.

وتتشابه العملية مع الدمج المحلي باستخدام Local Home SDK. بعد إتقان خطوات تحديد المشاكل وحلّها، يمكنك التنقّل بسهولة بين المقاييس والسجلات للحصول على إحصاءات حول الأخطاء.

يمكنك اختياريًا اختبار الإجراء من خلال مشاركته مع مستخدمين آخرين. احرص على التعامل مع الأخطاء والاستثناءات بشكل مناسب.

رصد الأخطاء

يمكنك استخدام Google Cloud Monitoring dashboard للوصول إلى مقاييس مشروعك. في ما يلي بعض الرسومات البيانية الرئيسية التي تفيد بشكل خاص في مراقبة الجودة وتصحيح الأخطاء:

مخطط معدل النجاح هو أول مخطط يجب البدء به عند مراقبة موثوقية مشاريعك. يمكن أن تشير الانخفاضات في هذا الرسم البياني إلى انقطاع الخدمة عن جزء من قاعدة المستخدمين أو كلها. ننصحك بمراقبة هذا الرسم البياني عن كثب لرصد أي مخالفات بعد كل تغيير أو تعديل في مشروعك.
مخطط وقت الاستجابة في الشريحة المئوية الخامسة والتسعين هو مؤشر مهم على أداء عملية دمج Cloud-to-cloud بالنسبة إلى المستخدمين. قد تشير التقلّبات المفاجئة في هذا الرسم البياني إلى أنّ أنظمتك قد لا تتمكّن من مواكبة الطلبات. ننصحك بالاطّلاع على هذا الرسم البياني بشكل دوري لرصد أي سلوك غير متوقّع.
تكون مخططات تفاصيل الخطأ مفيدة جدًا عند تحديد المشاكل في عمليات الدمج وحلّها. لكل خطأ يتم تمييزه في الرسم البياني الخاص بنسبة النجاح، يظهر رمز خطأ في تفاصيل الخطأ. يمكنك الاطّلاع على الأخطاء التي تم الإبلاغ عنها من خلال Google Home platform وكيفية تحديد المشاكل وحلّها في الجدول أدناه.

رموز الأخطاء الشائعة في المنصات

في ما يلي بعض رموز الخطأ الشائعة التي قد تظهر في سجلات مشروعك لتحديد المشاكل التي رصدتها Google Home platform. راجِع الجدول التالي للحصول على معلومات حول تحديد المشاكل وحلّها. للحصول على قائمة كاملة برموز الأخطاء، راجِع الأخطاء والاستثناءات.

رمز الخطأ	الوصف	الإجراء المطلوب من الشريك
`ACTION_NOT_AVAILABLE`	الأمر غير صالح لحالة الجهاز الحالية (على سبيل المثال، "ضبط درجة الحرارة" بينما الجهاز مطفأ). تحقَّق من سمات الجهاز ومنطق الحالة الحالية في عملية التنفيذ.	نعم
`AGENT_ISSUE`	حدثت مشكلة عامة في وكيل الشريك على السحابة الإلكترونية. ابحث عن استثناءات أو أعطال لم تتم معالجتها في سجلّات التنفيذ.	نعم
`AGENT_UNAVAILABLE_ERROR`	تعذّر على Google الوصول إلى عنوان URL الخاص بتنفيذ الطلبات لدى الشريك. تأكَّد من أنّ الخادم متصل بالإنترنت وأنّ جدار الحماية لا يحظر Google، وأنّ عنوان URL صحيح.	نعم
`APP_LAUNCH_FAILED`	تعذّر تشغيل تطبيق تابع لجهة خارجية على الجهاز المستهدَف. تأكَّد من صحة appId ومن أنّ التطبيق متوافق مع الجهاز المستهدَف.	نعم
`AUTH_EXPIRED`	انتهت صلاحية رمز الدخول عبر OAuth ولا يمكن إعادة تحميله. تحقَّق من تدوير الرمز المميز لإعادة التحميل وتأكَّد من أنّ المستخدم لم يبطل إذن الوصول.	نعم
`BACKEND_FAILURE_URL_TIMEOUT`	انتهت مهلة طلب Google عند محاولة الوصول إلى خدمتك. تأكَّد من أنّ خدمتك متاحة على الإنترنت وتقبل الاتصالات، ومن أنّها لا تتجاوز سعتها. بالإضافة إلى ذلك، تأكَّد من أنّ الجهاز المستهدف قيد التشغيل ومتصل بالإنترنت ومتزامن.
`BACKEND_FAILURE_URL_UNREACHABLE`	تلقّت Google رمز الخطأ HTTP 5xx من خدمتك. استخدِم `requestId` في Google Cloud Logging للتحقّق من سجلّات خدمة المنزل الذكي. التحقيق في أعطال الخادم أو انتهاء المهلة أو أخطاء البوابة 502/503
`CHANNEL_SWITCH_FAILED`	تعذّر على الجهاز التبديل إلى قناة الوسائط المطلوبة. تحقَّق من أسماء القنوات أو أرقامها وحالة اشتراك المستخدم.	نعم
`CHARGER_ISSUE`	يُبلغ الجهاز عن مشكلة في الأجهزة بنظام الشحن. على الشريك التحقيق في بيانات القياس عن بُعد على مستوى الأجهزة وصحة البطارية.	نعم
`CHECK_PARTNER_APP`	يتطلّب الخطأ من المستخدم فتح تطبيق الشريك لحلّ المشكلة. استخدِم هذا الرمز للأخطاء التي تتطلّب تفاعلاً معقّدًا مع واجهة المستخدم (على سبيل المثال، تحديثات البرامج الثابتة).	نعم
`COMMAND_FAILED`	حدث خطأ عام أثناء تنفيذ أمر. راجِع سجلّات التنفيذ بحثًا عن `requestId` المحدّد لتحديد السبب الأساسي.	نعم
`COMMAND_INSERT_FAILED`	تعذّر على Google وضع الأمر في قائمة الانتظار أو معالجته للجهاز. التحقيق في أداء الكتابة في قاعدة البيانات أو منطق ترتيب الأوامر الداخلية في قائمة الانتظار	نعم
`DEVICE_NOT_FOUND`	رقم تعريف الجهاز في الطلب غير متوفّر لدى الشريك. تأكَّد من أنّ الخلفية تحافظ دائمًا على مزامنة قاعدة البيانات Home Graph. يجب استدعاء `requestSync` عند إضافة أجهزة أو إزالتها.	نعم
`ERROR_STATUS`	أشارت الاستجابة إلى حالة "خطأ" غير محدّدة بدون رمز. يجب دائمًا تضمين سلسلة `errorCode` معيّنة لتحسين بيانات لوحة البيانات وتحويل النص إلى كلام للمستخدمين.	نعم
`EXECUTION_BACKEND_FAILURE_URL_ERROR`	تلقّت Google خطأ HTTP 4xx (غير 401) من عملية التنفيذ. تحقَّق من سجلّات خادم الويب بحثًا عن الردود 403 أو 404 أو 400.	نعم
`EXECUTION_BACKEND_FAILURE_URL_ROBOTED`	تم حظر عنوان URL الخاص بتنفيذ الطلب باستخدام ملف robots.txt أو فلاتر الأمان. تأكَّد من إمكانية وصول برامج الزحف/الخدمات من Google إلى نقطة نهاية التنفيذ.	نعم
`EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE`	تلقّت Google الخطأ HTTP 5xx من خدمة تنفيذ الطلبات. تأكَّد من أنّ خدمة عنوان URL لنقطة النهاية مستقرة وصحيحة ويمكن الوصول إليها بشكل علني، وأنّ الخدمة تعمل. إضافة عمليات التحقّق من الصحة ومعالجة إعادة المحاولة التحقيق في أعطال الخادم أو المهلات أو أخطاء البوابة 502/503	نعم
`EXECUTION_BAILOUT_INVALID_RESPONSE`	كانت استجابة JSON غير صالحة لدرجة أنّه تم إيقاف المعالجة. استخدِم مدقّق JSON للتأكّد من أنّ الرد يتّبع بدقة مخططات الأهداف.	نعم
`EXECUTION_GAL_BAD_3P_RESPONSE`	تعذّر ربط الحساب بسبب تنسيق غير صالح في رد الرمز المميّز. تأكَّد من أنّ تنسيق الردّ الذي يقدّمه خادم OAuth يتطابق مع متطلبات Google.	نعم
`EXECUTION_GAL_INSUFFICIENT_CAPABILITIES`	لا يملك حساب المستخدم الأذونات اللازمة لتنفيذ هذا الإجراء. تحقَّق من النطاقات المطلوبة أثناء عملية OAuth وتأكَّد من تطابقها مع السمات المطلوبة.	نعم
`EXECUTION_GAL_MAYBE_UNLINKED_BY_3P`	تشير السحابة الإلكترونية الخاصة بالشريك إلى أنّ المستخدم قد ألغى ربط حسابه. تأكَّد من أنّ عملية الربط بين `agentUserId` ثابتة ولم يتم محوها.	نعم
`EXECUTION_GAL_READ_ONLY_MODE_FOR_3P`	يكون التكامل في حالة القراءة فقط من جهة الشريك. تحقَّق مما إذا كان حساب المستخدم معلّقًا أو في وضع الصيانة "للعرض فقط".	نعم
`EXECUTION_GAL_UNLINKED_BY_3P`	ألغت الخدمة التابعة لجهة خارجية ربط الحساب بشكل استباقي. تحقَّق من سبب قطع اتصال المستخدم (على سبيل المثال، إعادة الضبط لأسباب أمنية). تأكَّد من أنّ خادم OAuth الخاص بالشريك يستجيب بشكل صحيح لطلبات Google `refresh_token` لإصدار رموز مميّزة جديدة للوصول بسلاسة.	نعم
`EXECUTION_INVALID_JSON`	تعذّر على Google تحليل حمولة ردّ JSON. تحقَّق من عدم وجود أخطاء في البنية أو أقواس ناقصة أو أحرف غير صالحة في ردّك.	نعم
`FAULTY_BATTERY`	تشير أجهزة الجهاز إلى أنّ البطارية معطّلة أو فارغة. يجب توجيه المستخدم باستخدام ميزة "تحويل النص إلى كلام" أو التطبيق لاستبدال البطارية الفعلية.	نعم
`FUNCTION_NOT_SUPPORTED`	لا يتوافق الجهاز مع الوضع أو الوظيفة المطلوبَين. تأكَّد من أنّ ردّك على `SYNC` يعكس إمكانات الجهاز بدقة.
`HARD_ERROR`	يشير إلى خطأ غير عابر لا يمكن حله بدون تدخل يدوي. استخدِم هذا الرمز في حال حدوث أعطال دائمة في الأجهزة أو حالات حساب غير قابلة للاسترداد.	نعم
`INVALID_AUTH_TOKEN`	تلقّت Google رمز الخطأ HTTP 401 من خدمتك. لم تنتهِ صلاحية رمز الدخول، ولكن خدمتك أبطَلته. استخدِم `requestId` في Google Cloud Logging للتحقّق من سجلات خدمة المنزل الذكي.
`INVALID_JSON`	بنية الرد غير صالحة (مثلاً، الحقول الإلزامية غير متوفّرة). تحقَّق من صحة استجابتك مقارنةً بمخططات JSON الخاصة بالنوايا.	نعم
`LOCK_FAILURE`	تعذّر تغيير حالة القفل الذكي إلى الحالة المطلوبة. تحقَّق من حدوث أي أعطال ميكانيكية أو انخفاض في الطاقة أو أعطال في المحرك ضمن جهاز القفل.	نعم
`MALFORMED_JSON`	بنية JSON غير صالحة (على سبيل المثال، سلاسل أو عناصر غير مغلقة). تأكَّد من أنّ عملية التنفيذ تستخدم مكتبة JSON عادية لتسلسل الاستجابات.	نعم
`MISSING_STATE`	لم تتضمّن استجابة QUERY حالة الجهاز المطلوبة. تأكَّد من احتساب جميع السمات المحدّدة في `SYNC` في كل استجابة `QUERY` أو `EXECUTE`، ومن عرض جميع حالات السمات المطلوبة، حتى إذا لم تتغيّر.	نعم
`NETWORK_PROFILE_NOT_RECOGNIZED`	ملف تعريف الشبكة المطلوب غير معروف للجهاز. تأكَّد من أنّ سلسلة اسم الملف الشخصي تتطابق مع الملفات الشخصية المتوافقة في الردّ `SYNC`.	نعم
`NOT_IMPLEMENTED`	لم ينفّذ الشريك الغرض أو السمة المطلوبَين. يجب تضمين السمات التي تم تنفيذها بالكامل فقط في ردّك على `SYNC`.	نعم
`OAUTH_RECONNECT_CALL_TO_ACTION`	يؤدي إلى إرسال إشعار إلى المستخدم لإعادة ربط حسابه. استخدِم هذا النوع عندما يتم إبطال جلسة المستخدم ويتطلّب ذلك إعادة مصادقة OAuth يدويًا.	نعم
`OPEN_AUTH_FAILURE`	انتهت صلاحية رمز الدخول الخاص بالمستخدم وتعذّر على Google إعادة تحميله، أو تلقّت Google رمز الخطأ HTTP 401 من خدمتك. في حال ملاحظة زيادة في معدّل ظهور هذا الرمز، تحقَّق مما إذا كنت تلاحظ أيضًا زيادة في معدّل الأخطاء المتعلقة بطلبات الرموز المميزة لإعادة التحميل أو طلبات الأجهزة المنزلية الذكية.
`PARTNER_RESPONSE_INVALID_ERROR_CODE`	السلسلة `errorCode` التي تم عرضها ليست ضمن القائمة المتوافقة مع Google. ربط أخطائك الداخلية بقائمة الأخطاء الرسمية	نعم
`PARTNER_RESPONSE_INVALID_PAYLOAD`	الحقل `payload` في الردّ ليس عنصر JSON صالحًا. تحقَّق من بنية الجذر لردّ التنفيذ.	نعم
`PARTNER_RESPONSE_INVALID_STATUS`	لم يكن الردّ `status` SUCCESS أو ERROR أو OFFLINE. تأكَّد من أنّ كل نتيجة جهاز في ردّك تتضمّن سلسلة حالة صالحة.	نعم
`PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES`	لم تتضمّن الاستجابة نتائج لجميع الأوامر/الأجهزة المطلوبة. تحقَّق من صحة بنية الردّ مقارنةً بمستندات المطوّرين في Google Home. تأكَّد من عدم اقتطاع الاستجابة أو عرض نص فارغ بسبب حدوث خطأ داخلي في الخادم. يجب أن يتضمّن كل عنصر في مصفوفة `commands` للطلب إدخال ردّ مطابق.	نعم
`PARTNER_RESPONSE_MISSING_DEVICE`	تم حذف جهاز معيّن طلبته Google من الردّ. تأكَّد من أنّ ردّك يتضمّن كل `ID` تم توفيره في حمولة الطلب.	نعم
`PARTNER_RESPONSE_MISSING_PAYLOAD`	لم يتم تضمين الحقل الإلزامي `payload` في الردّ. تأكَّد من أنّ عنصر JSON من المستوى الأعلى يتضمّن المفتاح `payload`.	نعم
`PARTNER_RESPONSE_NOT_OBJECT`	تعذّر تحليل الردّ بالكامل كعنصر JSON. تحقَّق من وجود أحرف لاحقة أو محتوى غير JSON في نص استجابة HTTP. تأكَّد من أنّ `payload.commands[]` هو عنصر JSON صالح يتضمّن المعرّفات والحالة والحالات الاختيارية.	نعم
`PROTOCOL_ERROR`	حدث خطأ في بروتوكول الاتصال الأساسي. تحقَّق من المشاكل في عناوين HTTP أو حالات تعذُّر تأكيد الاتصال عبر طبقة المقابس الآمنة (SSL) أو بروتوكول أمان طبقة النقل (TLS).	نعم
`RELINK_REQUIRED`	على المستخدم إعادة ربط حسابه لمواصلة استخدام عملية الدمج. تأكَّد من أنّ الخادم يعرض هذا الرمز عندما يكون رمز التحديث المميز غير صالح نهائيًا.	نعم
`REQUEST_ID_NOT_FOUND`	لم يتمكّن محرّك بحث Google من العثور على رقم تعريف التتبُّع الداخلي للطلب. عادةً ما يكون هذا الخطأ ناتجًا عن مشكلة داخلية في المنصة. راقِب أي ارتفاعات مفاجئة في عدد الأخطاء وتواصَل مع فريق الدعم.	نعم
`RESOURCE_UNAVAILABLE`	المورد المطلوب (الجهاز أو السمة) غير متوفّر. تحقَّق ممّا إذا كان الجهاز "مشغولاً" أو تم إيقافه مؤقتًا.	نعم
`RESPONSE_TIMEOUT`	تعذّر على خدمة تنفيذ الطلبات الاستجابة في غضون 9 ثوانٍ. تحسين وقت استجابة الخلفية، والتحقّق من طلبات البحث البطيئة في قاعدة البيانات أو تأخّر الشبكة الإقليمية	نعم
`RESPONSE_UNAVAILABLE`	لم يتم تلقّي أي رد من عنوان URL الخاص بتنفيذ الطلبات لدى الشريك. تأكَّد من أنّ خدمتك تعمل وأنّ نقطة النهاية لا تتعطّل.	نعم
`SCENE_CANNOT_BE_APPLIED`	تعذّر تفعيل المشهد المطلوب (على سبيل المثال، عدم توفّر أجهزة). التحقّق من سلامة المشاهد الداخلية للمستخدم على السحابة الإلكترونية الخاصة بالشريك	نعم
`STREAM_UNPLAYABLE`	تعذّر بدء بث الكاميرا أو حدث خطأ فيه. تحقَّق من إشارات WebRTC/HLS وتأكَّد من صلاحية عنوان URL للبث.	نعم
`TIMEOUT`	حدثت مهلة عامة أثناء معالجة intent. راجِع السجلّات بحثًا عن حالات انتهاء المهلة للخدمة الداخلية بين السحابة الإلكترونية ومراكز الأجهزة.	نعم
`TRANSIENT_ERROR`	الخطأ العابر هو خطأ سيتم إصلاحه تلقائيًا. تظهر هذه الأخطاء عادةً على شكل انقطاع الاتصال بجهاز أو خدمة. ويحدث ذلك أيضًا إذا تعذّر فتح اتصالات جديدة بخادم.
`UNABLE_TO_LOCATE_DEVICE`	تعذّر العثور على الجهاز باستخدام سمة "أداة تحديد الموقع" (على سبيل المثال، تعذّر إرسال إشارة ping). تحقَّق من اتصال الجهاز بالشبكة المحلية (Wi-Fi أو البلوتوث).	نعم
`UNABLE_TO_RING_DEVICE`	تم الوصول إلى الجهاز ولكن تعذّر تشغيل وظيفة الرنين/التنبيه. تحقَّق من حالة التنبيه/مكبر الصوت ومستويات الصوت في الجهاز.	نعم
`UNABLE_TO_SILENCE_DEVICE`	تعذّر على الجهاز إيقاف التنبيه النشط أو الرنين. التحقيق في حالات فشل الاتصال بين السحابة الإلكترونية والجهاز الفعلي	نعم
`UNEXPECTED_ERROR_CHECK_DEVICE_APP`	حدث خطأ غير متوقّع، ويجب أن يتحقّق المستخدم من تطبيق الشريك. يُستخدَم هذا الرمز كرمز شامل للأخطاء التي ليس لها رمز مكافئ محدّد متوافق مع Google.	نعم
`UNKNOWN_ERROR`	خطأ عام بدون تقديم تفاصيل إضافية. أضِف عملية ربط مناسبة للأخطاء وعمليات تحقّق دفاعية وتسجيل للأحداث، وذلك لكي تعرض حالات الفشل المعروفة رموز أخطاء معيّنة بدلاً من الرموز العامة.	نعم
`UNLOCK_FAILURE`	تعذّر على القفل الذكي الوصول إلى الحالة "مفتوح". التحقّق من مشاكل تعذُّر فتح القفل بسبب مشاكل في الأجهزة أو انخفاض مستوى شحن البطارية أو إدخال رقم تعريف شخصي غير صالح	نعم

سجلات البحث

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

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

يمكنك استخدام أزرار طلب البحث لمساعدتك في إنشاء الفلاتر المخصّصة.

إنشاء طلبات بحث في سجلات السحابة الإلكترونية

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

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

استخدِم الزر درجة الأهمية للفلترة حسب حالة طارئة ومعلومات وتصحيح الأخطاء ومستويات سجلّ درجة الأهمية الأخرى.

يمكنك أيضًا استخدام الحقل "طلب البحث" في Logs Explorer لإدخال إدخالات مخصّصة. يتيح محرّك طلبات البحث المستخدَم في هذا الحقل طلبات البحث الأساسية، مثل مطابقة السلاسل، وأنواعًا أكثر تقدّمًا من طلبات البحث، بما في ذلك عوامل المقارنة (<, >=, !=) وعوامل التشغيل المنطقية (AND, OR, NOT).

على سبيل المثال، سيؤدي الإدخال المخصّص أدناه إلى عرض أخطاء مصدرها نوع الجهاز LIGHT:

resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"

انتقِل إلى مكتبة طلبات البحث للعثور على المزيد من الأمثلة حول طلبات البحث الفعّالة في السجلات.

اختبار الإصلاحات

بعد تحديد الأخطاء وتطبيق التعديلات لإصلاحها، ننصحك باختبار الإصلاحات بدقة باستخدام Google Home Test Suite. نقدّم دليل مستخدم حول كيفية استخدام Test Suite، وهو يرشدك إلى كيفية اختبار التغييرات بفعالية.

موارد التعلُّم

يوضّح هذا المستند خطوات تحديد وحلّ الأخطاء في تطبيق Smart Home. يمكنك أيضًا الاطّلاع على دروسنا البرمجية لمعرفة المزيد حول تصحيح الأخطاء:

تصحيح أخطاء Smart Home Codelab: دليل البدء السريع لتصحيح أخطاء عملية دمج السحابة الإلكترونية في المنزل الذكي
تصحيح أخطاء Local Home Codelab: دليل البدء السريع لتصحيح أخطاء عملية الدمج المحلية للمنزل الذكي

Cloud Logging