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

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

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

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

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

وتتشابه العملية مع عملية الدمج المحلية باستخدام 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 للتحقّق من سجلّات خدمة المنزل المزوّد بأجهزة ذكية.
`CHANNEL_SWITCH_FAILED`	تعذّر على الجهاز التبديل إلى قناة الوسائط المطلوبة. تحقَّق من أسماء القنوات أو أرقامها وحالة اشتراك المستخدم.	نعم
`CHARGER_ISSUE`	يُبلغ الجهاز عن مشكلة في الأجهزة بنظام الشحن. على الشريك التحقيق في القياس عن بُعد على مستوى الأجهزة وصحة البطارية.	نعم
`CHECK_PARTNER_APP`	يتطلّب الخطأ من المستخدم فتح تطبيق الشريك لحلّ المشكلة. استخدِم هذا الرمز للأخطاء التي تتطلّب تفاعلاً معقّدًا مع واجهة المستخدم (على سبيل المثال، تحديثات البرامج الثابتة).	نعم
`COMMAND_FAILED`	حدث خطأ عام أثناء تنفيذ أمر. راجِع سجلّات التنفيذ بحثًا عن `requestId` المحدّد لتحديد السبب الأساسي.	نعم
`COMMAND_INSERT_FAILED`	تعذّر على Google وضع الأمر في قائمة الانتظار أو معالجته للجهاز. التحقيق في أداء الكتابة في قاعدة البيانات أو منطق وضع الأوامر الداخلية في قائمة الانتظار	نعم
`DEVICE_NOT_FOUND`	رقم تعريف الجهاز في الطلب غير متوفّر لدى الشريك. تأكَّد من أنّ السحابة الإلكترونية تُفعِّل `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 من خدمة تنفيذ الطلبات. التحقيق في أعطال الخادم أو المهلات أو أخطاء البوابة 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`	ألغت الخدمة التابعة لجهة خارجية ربط الحساب بشكل استباقي. تحقَّق من سبب قطع اتصال المستخدم (على سبيل المثال، إعادة ضبط الأمان).	نعم
`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`.	نعم
`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`	لم تتضمّن الاستجابة نتائج لجميع الأوامر/الأجهزة المطلوبة. يجب أن يتضمّن كل عنصر في مصفوفة `commands` الخاصة بالطلب إدخال رد مطابق.	نعم
`PARTNER_RESPONSE_MISSING_DEVICE`	تم حذف جهاز معيّن طلبته Google من الردّ. تأكَّد من أنّ ردّك يتضمّن كل `ID` تم تقديمه في حمولة الطلب.	نعم
`PARTNER_RESPONSE_MISSING_PAYLOAD`	لم يتم تضمين الحقل الإلزامي `payload` في الردّ. تأكَّد من أنّ عنصر JSON من المستوى الأعلى يتضمّن المفتاح `payload`.	نعم
`PARTNER_RESPONSE_NOT_OBJECT`	تعذّر تحليل الردّ بالكامل كعنصر JSON. تحقَّق من وجود أحرف لاحقة أو محتوى غير JSON في نص استجابة HTTP.	نعم
`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`	حدثت مهلة عامة أثناء معالجة الغرض. راجِع السجلّات بحثًا عن حالات انتهاء المهلة للخدمة الداخلية بين السحابة الإلكترونية ومراكز الأجهزة.	نعم
`TRANSIENT_ERROR`	الخطأ العابر هو خطأ سيتم إصلاحه تلقائيًا. تظهر هذه الأخطاء عادةً على شكل انقطاع الاتصال بجهاز أو خدمة. ويحدث ذلك أيضًا إذا تعذّر فتح اتصالات جديدة بخادم.
`UNABLE_TO_LOCATE_DEVICE`	تعذّر العثور على الجهاز باستخدام سمة "أداة تحديد الموقع" (على سبيل المثال، تعذّر إرسال إشارة). تحقَّق من اتصال الجهاز بالشبكة المحلية (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، يشرح لك كيفية اختبار التغييرات التي أجريتها بفعالية.

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

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

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

Cloud Logging