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

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

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

1. قبل البدء

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

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

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

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

ما الذي ستنشئه

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

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

كيفية استخدام مقاييس 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 باستخدام مشروع "الإجراءات" المضمّن في ربط الأجهزة المنزلية الذكية بالدرس التطبيقي حول الترميز في "مساعد 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، أريد إيقاف الغسّالة"

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

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

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

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

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

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

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

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

سينقلك ذلك إلى قائمة بلوحات البيانات الخاصة بمشروعك على Google Cloud. اختَر لوحة بيانات إحصاءات صفحة Google الرئيسية - دمج 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);
};

اختبار الحلّ

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

firebase deploy --only functions

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

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

=>

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

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

=>

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

مُمْكِنْ كَمَانْ تِكُونْ حَالَة حَالِةِ الْغَسَّالَة عَنْ طَرِيقْ تَوْجِيهْ أَسْئِلَة.

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

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

4. اختبار الإجراء باستخدام مجموعة أدوات الاختبار

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

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

اتّبِع هذه التعليمات لاختبار "الإجراء للمنزل المزوّد بأجهزة ذكية" من خلال "حزمة الاختبار":

في متصفّح الويب، افتح مجموعة الاختبار للمنزل المزوّد بأجهزة ذكية.
سجِّل الدخول إلى 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,
              },
            },
          },
        },
      };
      ...
    });

اختبار الحلّ

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

$ firebase deploy --only functions

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

5- تهانينا

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

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

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

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

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