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

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

1- قبل البدء

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

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

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

قراءة دليل المطوّرين إنشاء عملية دمج من السحابة الإلكترونية إلى السحابة الإلكترونية
تشغيل برنامج ربط الأجهزة المنزلية الذكية بخدمة "مساعد 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، ثمّ أعدّ واجهة سطر الأوامر (CLI) في Firebase باستخدام مشروع الدمج الذي تم إنشاؤه في التدريب العملي حول ربط الأجهزة المنزلية الذكية بخدمة "مساعد 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" صوتيًا بوجود مشكلة عند إيقاف الغسالة مؤقتًا أو استئناف عملها:

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

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

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

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

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

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

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

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

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

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

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

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

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

في حقل الإدخال البحث في جميع الحقول، أدخِل طلب البحث 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، ما هي دورة الغسيل التي تعمل بها الغسالة؟

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

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

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

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

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

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

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

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

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

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

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

تشير رسالة الخطأ إلى أنّ "مجموعة الاختبارات" تتوقّع "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- تهانينا

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

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

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

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

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

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

1- قبل البدء

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

ما ستنشئه

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

المتطلبات

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

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

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

الربط مع Firebase

النشر على Firebase

تعديل HomeGraph

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

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

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

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

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

إصلاح الخطأ

اختبار الحلّ

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

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

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

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

إصلاح الخطأ

اختبار الحلّ

5- تهانينا

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

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