بدء مسابقة المطوّرين لواجهات برمجة التطبيقات في 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. راجِع الجدول التالي للحصول على معلومات حول تحديد المشاكل وحلّها. للحصول على قائمة كاملة برموز الأخطاء، راجِع الأخطاء والاستثناءات.

رمز الخطأ	الوصف	الإجراء المطلوب من الشريك
`AGENT_ISSUE`	حدثت مشكلة عامة في وكيل الشريك على السحابة الإلكترونية. ابحث عن الاستثناءات أو الأعطال التي لم يتم التعامل معها في سجلّات التنفيذ.	نعم
`AGENT_UNAVAILABLE_ERROR`	تعذّر على Google الوصول إلى عنوان URL الخاص بتنفيذ الطلبات لدى الشريك. تأكَّد من أنّ الخادم متصل بالإنترنت وأنّ جدار الحماية لا يحظر Google، وأنّ عنوان URL صحيح.	نعم
`BACKEND_FAILURE_URL_TIMEOUT`	انتهت مهلة طلب Google عند محاولة الوصول إلى خدمتك. تأكَّد من أنّ خدمتك متاحة على الإنترنت وتقبل الاتصالات، ومن أنّها لا تتجاوز سعتها. بالإضافة إلى ذلك، تأكَّد من أنّ الجهاز المستهدف مشغّل ومتصل بالإنترنت ومتزامن.
`BACKEND_FAILURE_URL_UNREACHABLE`	تلقّت Google رمز خطأ HTTP 5xx من خدمتك. استخدِم `requestId` في Google Cloud Logging للتحقّق من سجلّات خدمة المنزل المزوّد بأجهزة ذكية. التحقيق في أعطال الخادم أو انتهاء المهلة أو أخطاء البوابة 502/503
`COMMAND_FAILED`	حدث خطأ عام أثناء تنفيذ أمر. راجِع سجلّات التنفيذ بحثًا عن `requestId` المحدّد لتحديد السبب الأساسي.	نعم
`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_NOT_FOUND`	رموز الدخول والتحديث الخاصة بالمستخدم والمخزَّنة في Google غير صالحة أو لا يمكن إعادة تحميلها، ما يمنع المصادقة والوصول إلى خدمة الشريك. يجب التأكّد من أنّ الرموز المميزة تظل صالحة ومتزامنة، والتعامل مع تغييرات حالة الحساب بشكل مناسب، وطلب إعادة ربط الحساب إذا تم التأكّد من إبطال الرموز المميزة.	نعم
`EXECUTION_GAL_READ_ONLY_MODE_FOR_3P`	يكون التكامل في حالة القراءة فقط من جهة الشريك. تحقَّق مما إذا كان حساب المستخدم معلّقًا أو في وضع الصيانة "للمشاهدة فقط".	نعم
`EXECUTION_GAL_UNLINKED_BY_3P`	ألغت الخدمة التابعة لجهة خارجية ربط الحساب بشكل استباقي. تحقَّق من سبب قطع اتصال المستخدم (على سبيل المثال، إعادة ضبط الأمان). تأكَّد من أنّ خادم OAuth الخاص بالشريك يستجيب بشكل صحيح لطلبات Google `refresh_token` لإصدار رموز مميّزة جديدة للوصول بسلاسة.	نعم
`EXECUTION_INVALID_JSON`	تعذّر على Google تحليل حمولة استجابة JSON. تحقَّق من عدم وجود أخطاء في البنية أو أقواس ناقصة أو أحرف غير صالحة في ردّك.	نعم
`INVALID_AUTH_TOKEN`	تلقّت Google رمز الخطأ HTTP 401 من خدمتك. لم تنتهِ صلاحية رمز الدخول، ولكن خدمتك أبطَلته. استخدِم `requestId` في Google Cloud Logging للتحقّق من سجلّات خدمة المنزل المزوّد بأجهزة ذكية.
`INVALID_JSON`	بنية الرد غير صالحة (مثلاً، الحقول الإلزامية غير متوفّرة). تحقَّق من صحة استجابتك مقارنةً بمخططات JSON الخاصة بالنوايا.	نعم
`MALFORMED_JSON`	بنية JSON غير صالحة (على سبيل المثال، سلاسل أو عناصر غير مغلقة). تأكَّد من أنّ عملية التنفيذ تستخدم مكتبة JSON عادية لتسلسل الاستجابات.	نعم
`NOT_IMPLEMENTED`	لم ينفّذ الشريك الغرض أو السمة المطلوبَين. يجب تضمين السمات التي تم تنفيذها بالكامل فقط في ردّ `SYNC`.	نعم
`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 صالح يتضمّن المعرّفات والحالة والحالات الاختيارية.	نعم
`REQUEST_ID_NOT_FOUND`	لم يتمكّن محرّك بحث Google من العثور على رقم تعريف التتبُّع الداخلي للطلب. عادةً ما يكون هذا الخطأ ناتجًا عن مشكلة داخلية في المنصة. راقِب أي ارتفاعات مفاجئة في عدد الأخطاء وتواصَل مع فريق الدعم.	نعم
`RESOURCE_UNAVAILABLE`	المورد المطلوب (الجهاز أو السمة) غير متوفّر. تحقَّق ممّا إذا كان الجهاز "مشغولاً" أو تم إيقافه مؤقتًا.	نعم
`RESPONSE_TIMEOUT`	تعذّر على خدمة تنفيذ الطلبات الاستجابة في غضون 9 ثوانٍ. تحسين وقت استجابة الخلفية، والتحقّق من بطء طلبات البحث في قاعدة البيانات أو تأخّر الشبكة الإقليمية	نعم
`RESPONSE_UNAVAILABLE`	لم يتم تلقّي أي رد من عنوان URL الخاص بتنفيذ الطلبات لدى الشريك. تأكَّد من أنّ خدمتك تعمل وأنّ نقطة النهاية لا تتعطّل.	نعم
`TIMEOUT`	حدثت مهلة عامة أثناء معالجة الغرض. راجِع السجلّات بحثًا عن حالات انتهاء المهلة للخدمة الداخلية بين السحابة الإلكترونية ومراكز الأجهزة.	نعم

سجلات البحث

بعد أن تصبح معتادًا على مراقبة عمليات الدمج باستخدام المقاييس، ستكون الخطوة التالية هي تحديد المشاكل وحلّها باستخدام 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 Action. يمكنك أيضًا الاطّلاع على دروسنا البرمجية لمعرفة المزيد حول تصحيح الأخطاء:

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

Cloud Logging