اكتملت عملية نقل البيانات إلى "مركز مطوّري Google Home".

تصحيح الأخطاء في المنزل المزوّد بأجهزة ذكية

‫1. قبل البدء

بصفتك مطوّرًا في مجال إنترنت الأشياء (IoT)، يمكنك إنشاء عمليات دمج بين الخدمات السحابية تتيح للمستخدمين التحكّم في أجهزتهم من خلال عناصر التحكّم باللمس في تطبيق Google Home والطلبات الصوتية باستخدام "مساعد Google".

يُعدّ التعرّف على أدوات تصحيح الأخطاء لعمليات الدمج من السحابة الإلكترونية إلى السحابة الإلكترونية خطوة مهمة لإنشاء عمليات دمج عالية الجودة مع "مساعد Google". لتسهيل عملية الرصد وتصحيح الأخطاء، تتوفّر مقاييس Google Cloud Platform (GCP) والتسجيل ومجموعة الاختبارات للمنزل المزوّد بأجهزة ذكية لمساعدتك في تحديد المشاكل وحلّها في عمليات الدمج.

المتطلبات الأساسية

قراءة دليل المطوّرين إنشاء عملية دمج من السحابة الإلكترونية إلى السحابة الإلكترونية
تشغيل برنامج ربط الأجهزة المنزلية الذكية بخدمة "مساعد Google" التعليمي

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستنشر عملية دمج من السحابة الإلكترونية إلى السحابة الإلكترونية تتضمّن عيبَين وتربطها بخدمة "مساعد Google"، ثم ستصحّح عيوب عملية الدمج باستخدام "مجموعة الاختبارات للمنزل المزوّد بأجهزة ذكية" و"مقاييس Google Cloud Platform‏ (GCP) وتسجيل البيانات".

أهداف الدورة التعليمية

كيفية استخدام مقاييس وتسجيل GCP لتحديد مشاكل الإنتاج وحلّها
كيفية استخدام "مجموعة الاختبارات للأجهزة المنزلية الذكية" لتحديد المشاكل الوظيفية ومشاكل واجهة برمجة التطبيقات

المتطلبات

متصفّح ويب، مثل Google Chrome
جهاز iOS أو Android مثبَّت عليه تطبيق Google Home
الإصدار 10.16 من Node.js أو إصدار أحدث
حساب فوترة على Google Cloud

‫2. تشغيل التطبيق الذي يتضمّن أخطاء

الحصول على رمز المصدر

انقر على الرابط التالي لتنزيل نموذج لهذا الدرس العملي حول الترميز على جهاز التطوير:

...أو يمكنك استنساخ مستودع GitHub من سطر الأوامر:

$ git clone https://github.com/google-home/smarthome-debug.git

لمحة عن المشروع

يحتوي تطبيق الغسالة على الدلائل الفرعية التالية:

‫public: واجهة مستخدم أمامية للتحكّم بسهولة في حالة الغسالة الذكية ومراقبتها.
‫functions: خدمة سحابية تم تنفيذها بالكامل وتدير الغسالة الذكية باستخدام وظائف Firebase السحابية وقاعدة بيانات Firebase في الوقت الفعلي

الربط مع Firebase

افتح نافذة طرفية على جهاز التطوير. انتقِل إلى الدليل washer-faulty، ثمّ أعدّ Firebase CLI باستخدام مشروع الدمج الذي تمّ إنشاؤه في التدريب العملي حول ربط الأجهزة المنزلية الذكية بخدمة "مساعد Google":

$ cd washer-faulty
$ firebase use <firebase-project-id>

النشر على Firebase

انتقِل إلى المجلد functions وثبِّت جميع التبعيات الضرورية باستخدام npm.

$ cd functions
$ npm install

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

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

بعد تثبيت التبعيات وإعداد مشروعك، يمكنك الآن نشر تطبيق الغسالة المعطّلة.

$ firebase deploy

في ما يلي نتائج وحدة التحكّم التي من المفترض أن تظهر لك:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<Firebase-project-id>/overview
Hosting URL: https://<Firebase-project-id>.firebaseapp.com

تعديل HomeGraph

افتح عنوان URL للاستضافة في المتصفّح (https://<firebase-project-id>.firebaseapp.com) لعرض تطبيق الويب. في واجهة مستخدم الويب، انقر على الزر إعادة تحميل لتعديل HomeGraph باستخدام أحدث البيانات الوصفية للجهاز من تطبيق الغسالة المعطّلة باستخدام طلب المزامنة.

افتح تطبيق Google Home وتأكَّد من إمكانية رؤية الغسالة التي تحمل الاسم غسالة معطّلة.

3- اختبار عملية الدمج

بعد نشر مشروعك، اختبِر ما إذا كانت عملية الدمج تتحكّم في الغسالة.

اختبار الغسالة

تحقَّق من تغيُّر القيمة عند تجربة أيّ من الأوامر الصوتية التالية من خلال هاتفك:

"Ok Google، شغِّل الغسالة".

Ok Google، شغِّل الغسالة".

"Ok Google، أوقِف الغسالة مؤقتًا".

"Ok Google، استأنِف تشغيل الغسالة".

"Ok Google، أوقِف الغسالة".

سيُعلمك "مساعد Google" صوتيًا بوجود مشكلة عند إيقاف الغسالة مؤقتًا أو استئناف عملها:

"عذرًا، لم أتمكّن من الوصول إلى <اسم العرض الخاص بالمشروع>."

لتصحيح هذا الخطأ، عليك أولاً الحصول على مزيد من المعلومات عنه لتضييق نطاق البحث وتحديد السبب الأساسي.

لوحة بيانات "إحصاءات المنزل الذكي"

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

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

لتحديد سبب الخطأ، اتّبِع الخطوات التالية للوصول إلى لوحة بيانات المشروع.

في Play Console، انتقِل إلى صفحة "المشاريع".
اختَر مشروع المنزل الذكي.
انقر على علامة التبويب الإحصاءات في القائمة اليمنى.

سيؤدي ذلك إلى نقلك إلى قائمة لوحات بيانات لمشروعك على Google Cloud. اختَر لوحة بيانات إحصاءات Google Home - الدمج مع السحابة الإلكترونية.

انتقِل للأسفل إلى الرسم البياني أخطاء التنفيذ عبر السحابة الإلكترونية - تقسيم حسب الحالة لعرض رموز الخطأ للنطاق الزمني المميّز.

يقدّم رمز الخطأ PARTNER_RESPONSE_MISSING_DEVICE تلميحًا إلى السبب الأساسي. بعد ذلك، استرجِع سجلّات الأحداث استنادًا إلى رمز الخطأ للحصول على مزيد من التفاصيل.

الوصول إلى سجلات الأحداث

للحصول على مزيد من التفاصيل حول الخطأ، يمكنك الوصول إلى سجلّات الأحداث لعملية الدمج من السحابة الإلكترونية إلى السحابة الإلكترونية باستخدام Cloud Logging.

افتح قائمة التنقّل في Google Cloud Platform، وضِمن العمليات، اختَر تسجيل الدخول > مستكشف السجلات للوصول إلى سجلّات الأحداث الخاصة بمشروعك. بدلاً من ذلك، يمكنك البحث عن Logs Explorer في مربّع البحث.

في حقل الإدخال البحث في جميع الحقول، أدخِل طلب البحث PARTNER_RESPONSE_MISSING_DEVICE وانقر على تنفيذ طلب البحث. يتم عرض السجلات المطابقة لطلب البحث في قسم النتائج.

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

الإجراء الذي اتّخذه المستخدم هو "استئناف الغسالة" (actionType: "STARTSTOP_UNPAUSE")، وهو يتوافق مع الأمر الصوتي الأخير الذي تعذّر تنفيذه.
رسالة تصحيح الأخطاء المرتبطة هي "JSON response does not include device."

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

تحديد السبب الأساسي للخطأ

في functions/index.js، ابحث عن معالج EXECUTE (في مصفوفة onExecute) الذي يعرض حالة كل أمر وحالة الجهاز الجديدة. يعتمد إدراج أرقام تعريف الأجهزة في استجابة EXECUTE على حلّ الدالة updateDevice:

index.js

app.onExecute(async (body) => {
 ...

 for (const command of intent.payload.commands) {
   for (const device of command.devices) {
     for (const execution of command.execution) {
       executePromises.push(
           updateDevice(execution, device.id)
               .then((data) => {
                 result.ids.push(device.id);
                 Object.assign(result.states, data);
               })
               .catch((e) =>
                 functions.logger.error('EXECUTE',
                     device.id, e.message)));
     }
   }
 }

تحقَّق أيضًا من طريقة تعامل الدالة updateDevice مع الإيقاف المؤقت / الاستئناف في الغسالة، وستجد أنّ السلسلة التي يجب مطابقتها مع أمر الإيقاف المؤقت / الاستئناف غير صحيحة:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpausePause':
      const data = await queryDevice(deviceId);
      state = (data.isPaused === false && data.isRunning === false)
        ? {isRunning: false, isPaused: false}
        : {isRunning: !params.pause, isPaused: params.pause};
      ref = getFirebaseRef().child(deviceId).child('StartStop');
      break;
 }

 return ref.update(state)
     .then(() => state);
};

إصلاح الخطأ

بعد تحديد السبب الجذري للخطأ، يمكنك تصحيح السلسلة الخاصة بأمر الإيقاف المؤقت / الاستئناف باتّباع الخطوات التالية:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpause':
      const data = await queryDevice(deviceId);
      state = (data.isPaused === false && data.isRunning === false)
        ? {isRunning: false, isPaused: false}
        : {isRunning: !params.pause, isPaused: params.pause};
      ref = getFirebaseRef().child(deviceId).child('StartStop');
      break;
 }

 return ref.update(state)
     .then(() => state);
};

اختبار الحلّ

انشر الرمز المعدَّل باستخدام Firebase CLI:

firebase deploy --only functions

أعِد تجربة الأوامر الصوتية التالية، وستجد أنّ "مساعد Google" يستجيب بشكل صحيح الآن عند إيقاف الغسالة مؤقتًا أو استئنافها.

"Ok Google، أوقِف الغسالة مؤقتًا".

"حسنًا، سأوقف الغسالة مؤقتًا".

"Ok Google، استأنِف الغسالة"

"حسنًا، سأستأنف تشغيل الغسالة".

يمكنك أيضًا اختبار الحالة الحالية للغسالة من خلال طرح أسئلة.

"Ok Google، هل الغسالة تعمل؟"

Ok Google، هل الغسالة تعمل؟

Ok Google، ما هي دورة الغسيل التي تعمل بها الغسالة؟

4. اختبار عملية التكامل باستخدام "مجموعة أدوات الاختبار"

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

تشغيل "مجموعة الاختبارات للمنزل الذكي"

اتّبِع التعليمات التالية لاختبار عملية الربط بين الخدمات السحابية باستخدام "مجموعة الاختبارات":

في متصفّح الويب، افتح مجموعة الاختبارات للمنزل الذكي.
سجِّل الدخول إلى Google باستخدام الزرّ في أعلى يسار الصفحة. يتيح ذلك لـ Test Suite إرسال الأوامر مباشرةً إلى "مساعد Google".
في حقل معرّف المشروع، أدخِل رقم تعريف المشروع الخاص بعملية الربط بين الخدمات المستندة إلى السحابة الإلكترونية. بعد ذلك، انقر على التالي للمتابعة.
في خطوة إعدادات الاختبار، ستعرض "مجموعة الاختبارات" نوع الجهاز وسمات الغسّالة.

أوقِف الخيار مزامنة طلب الاختبار لأنّ تطبيق الغسالة النموذجية لا يتضمّن واجهة مستخدم لإضافة الغسالة أو إزالتها أو إعادة تسميتها. في نظام الإنتاج، عليك تفعيل طلب المزامنة كلما أضاف المستخدم أجهزة أو أزالها أو أعاد تسميتها.
انقر على التالي لبدء الاختبار.

بعد اكتمال تشغيل Test Suite، اطّلِع على نتائج حالات الاختبار. ستلاحظ حالتين اختبار غير ناجحتين تم رصدهما مع رسالة الخطأ ذات الصلة:

لتصحيح أخطاء عملية الدمج بين الخدمات المستندة إلى السحابة الإلكترونية، عليك تحديد السبب الجذري للخطأ من خلال تحليل رسالة الخطأ أولاً.

تحليل رسالة الخطأ

لمساعدة المطوّرين في تحديد السبب الأساسي للمشكلة، تعرض "حزمة الاختبار" رسائل خطأ لكل حالة اختبار فاشلة تشير إلى سبب الفشل.

بالنسبة إلى حالة الاختبار الفاشلة الأولى أعلاه،

تشير رسالة الخطأ إلى أنّ Test Suite تتوقّع "isPause": true في الحالات التي يتم الإبلاغ عنها من عملية الربط بين السحابة الإلكترونية والسحابة الإلكترونية، ولكن الحالات الفعلية تتضمّن "isPause": false فقط.

بالإضافة إلى ذلك، تشير رسالة الخطأ في حالة الاختبار الثانية التي تعذّر تنفيذها إلى أنّ الحالات في الردّ QUERY من عملية الربط بين الخدمات المستندة إلى السحابة الإلكترونية تتضمّن "isPause": true، وهو ما يختلف عن "isPause": false في الحالات التي تم إعداد تقارير عنها من عملية الربط بين الخدمات المستندة إلى السحابة الإلكترونية:

وفقًا لرسالتَي الخطأ، عليك بعد ذلك التحقّق ممّا إذا كانت تقارير الدمج تعرض isPaused بالقيمة الصحيحة.

تحديد السبب الأساسي للخطأ

افتح functions/index.js، الذي يحتوي على الدالة reportstate التي تنشر تغييرات الحالة إلى Home Graph باستخدام Report State. افحص حمولة Report State، وستجد أنّ الحمولة لا تتضمّن الحالة isPaused، وهو ما بحثت عنه "مجموعة الاختبار" بالضبط في حالات الاختبار الفاشلة.

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: snapshot.online,
                on: snapshot.OnOff.on,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      ...
    });

إصلاح الخطأ

بعد تحديد السبب الأساسي للخطأ، عدِّل functions/index.js عن طريق إضافة الحالة isPaused إلى حمولة Report State:

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: snapshot.online,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

اختبار الحلّ

انشر الرمز المعدَّل باستخدام Firebase CLI:

$ firebase deploy --only functions

أعِد تشغيل "مجموعة الاختبارات" للمنزل المزوّد بأجهزة ذكية، وستجد أنّ جميع حالات الاختبار قد اجتازت الاختبار.

5. تهانينا

تهانينا! لقد تعلّمت بنجاح كيفية تحديد المشاكل وحلّها في عملية الربط بين الخدمات السحابية باستخدام "مجموعة الاختبارات للمنزل المزوّد بأجهزة ذكية" و"مقاييس وسجلات Google Cloud Platform".

مزيد من المعلومات

استنادًا إلى هذا الدرس التطبيقي حول الترميز، جرِّب التمارين التالية واستكشِف المراجع الإضافية:

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

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

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

‫1. قبل البدء

المتطلبات الأساسية

ما ستنشئه

أهداف الدورة التعليمية

المتطلبات

‫2. تشغيل التطبيق الذي يتضمّن أخطاء

الحصول على رمز المصدر

لمحة عن المشروع

الربط مع Firebase

النشر على Firebase

تعديل HomeGraph

3- اختبار عملية الدمج

اختبار الغسالة

لوحة بيانات "إحصاءات المنزل الذكي"

الوصول إلى سجلات الأحداث

تحديد السبب الأساسي للخطأ

إصلاح الخطأ

اختبار الحلّ

4. اختبار عملية التكامل باستخدام "مجموعة أدوات الاختبار"

تشغيل "مجموعة الاختبارات للمنزل الذكي"

تحليل رسالة الخطأ

تحديد السبب الأساسي للخطأ

إصلاح الخطأ

اختبار الحلّ

5. تهانينا

مزيد من المعلومات

تصحيح الأخطاء في المنزل المزوّد بأجهزة ذكية