مرحبًا بك في "مركز مطوّري Google Home"، الوجهة الجديدة لتعلّم كيفية تطوير المهام المنزلية الذكية. ملاحظة: ستواصل إنشاء إجراءات في "وحدة تحكّم المهام".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

1- قبل البدء

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

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

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

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

العناصر التي ستنشئها

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

المعلومات التي ستطّلع عليها

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

المتطلبات

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

2- تشغيل التطبيق الذي يتضمّن عيوبًا

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

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

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

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

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

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

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

الربط بمنصة Firebase

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

$ cd washer-faulty
$ firebase use <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/<project-id>/overview
Hosting URL: https://<project-id>.firebaseapp.com

تعديل HomeGraph

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

يُرجى فتح تطبيق Google Home والتأكّد من ظهور الجهاز الذي يحمل اسم الغسّالة الخاطئة.

3- اختبار الإجراء الخاص بك

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

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

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

"Ok Google، أريد تشغيل غسّالة ملابسي"

"Ok Google، أريد تشغيل الغسّالة"

"Ok Google، أريد إيقاف الغسّالة مؤقتًا"

"Ok Google، أريد استئناف تشغيل الغسّالة"

"Ok Google، أريد إيقاف الغسّالة"

ملاحظة: عند إيقاف تشغيل الغسّالة مؤقتًا أو استئناف تشغيلها، سيردّ "مساعد Google" بأنّ هناك خطأ:

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

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

لوحة بيانات إحصاءات Smarthome

تُعدّ لوحة بيانات "إحصاءات Smarthome" مكانًا جيدًا لفحص الأخطاء، وهي تُجمِّع الرسوم البيانية لمقاييس الاستخدام والصحة من أجل توفير الخدمات السحابية:

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

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

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

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

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

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

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

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

افتح قائمة التنقل في 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':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.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':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

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

اختبار الحلّ

نشر الرمز المعدَّل باستخدام واجهة سطر الأوامر في Firebase:

firebase deploy --only functions

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

"Ok Google، أريد إيقاف الغسّالة مؤقتًا".

"بالتأكيد، جارٍ إيقاف الغسّالة مؤقتًا"

"Ok Google، أريد استئناف تشغيل الغسّالة".

"حسنًا، جارٍ استئناف تشغيل الغسّالة"

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

"Ok Google، هل غسّالة ملابسي قيد التشغيل؟"

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

"Ok Google، ما هي دورة التشغيل الحالية في غسّالة ملابسي؟"

4- اختبار الإجراء الخاص بك باستخدام حزمة الاختبار

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

تشغيل حزمة الاختبار للمنزل المزوّد بأجهزة ذكية

اتّبِع التعليمات التالية لاختبار تنفيذ "المهام مع مساعد Google" في المنزل المزوّد بأجهزة ذكية:

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

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

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

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

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

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

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

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

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

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

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

افتح functions/index.js، الذي يحتوي على الدالة reportstate التي تنشر تغييرات الحالة إلى الرسم البياني الرئيسي من خلال "حالة التقرير". افحص حمولة بيانات حالة التقرير، وستلاحظ أنّ الحمولة لا تتضمن حالة 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: true,
                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 إلى حمولة بيانات "حالة التقرير":

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: true,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

اختبار الحلّ

نشر الرمز المعدَّل باستخدام واجهة سطر الأوامر في Firebase:

$ firebase deploy --only functions

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

5- تهانينا

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

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

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

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

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