معالجة الأخطاء والاستثناءات

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

يقدّم هذا الدليل بعض الأمثلة على الردود على الطلبات التي تعالج الأخطاء. اطّلِع على الأخطاء والاستثناءات لمراجعة قيم errorCode الصالحة للأخطاء والاستثناءات.

المثال 1: ردّ يتضمّن خطأ لطلب EXECUTE

لدى المستخدم النهائي مصباحان ذكيان في غرفة المعيشة. يصدر المستخدم أمرًا "تشغيل أضواء الشاشات الكبيرة" وأرسلت Google EXECUTE intent إلى عنوان URL الخاص بالتنفيذ. تبيّن لك أنّ أجهزة المستخدم غير متصلة بالإنترنت ولا يمكن التحكّم فيها، لذا يعرض التنفيذ ردًّا من النوع EXECUTE مع ERROR status وdeviceOffline errorCode.

يوضّح هذا المثال كيفية عرض استجابة EXECUTE مع errorCode من جهاز خفيف كما هو موضّح سابقًا:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "light-device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "light-device-id-2"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

يظهر للمستخدم على Google Assistant رسالة "الجهاز غير متاح حاليًا" بعد تلقّي الردّ. يُرجى العِلم أنّه لا يزال عليك إرسال حالة عدم الاتصال للأجهزة في طلب report state بعد إرسال errorCode deviceOffline في ردّ EXECUTE.

المثال 2: استثناء غير مانع لغرض EXECUTE

يحاول مستخدم قفل القفل الذكي على بابه الأمامي باستخدام Assistant. يمكنك التحكّم في القفل بنجاح، ولكن مستوى شحن بطارية الجهاز منخفض، لذا يعرض التنفيذ استجابة EXECUTE مع status SUCCESS وexceptionCode lowBattery.

يوضّح هذا المثال كيفية إرسال استجابة EXECUTE مع exceptionCode من جهاز قفل كما هو موضّح سابقًا:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["lock-device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

يعرض Assistant للمستخدم رسالة "مستوى شحن بطارية الجهاز منخفض" بعد تلقّي الردّ.

المثال 3: إشعارات الأخطاء الاستباقية

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

مجفّف ملابس ذكي قيد التشغيل، ويفتح شخص ما الباب قبل انتهاء الدورة. يمكنك طلب إجراء reportStateAndNotifications في واجهة برمجة التطبيقات Google Home Graph لإرسال إشعار استباقي يتضمّن errorCode:

يوضّح هذا المثال كيفية إرسال إشعار استباقي يتضمّن errorCode من جهاز مجفّف ملابس كما هو موضّح سابقًا:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "dryer-device-id": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      },
      "states": {
        "dryer-device-id": {
          "isRunning": false,
          "isPaused": true
        }
      }
    }
  }
}

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

المثال 4: إشعار المتابعة

بالنسبة إلى أوامر السمات التي تتيح إرسال إشعارات المتابعة، يمكنك إرسال إشعار متابعة إلى المستخدم في حال حدوث خطأ أو استثناء، إذا كنت قد نفّذت smart home إشعارات المتابعة.

يصدر مستخدم أمرًا بإغلاق باب المرآب، ولكن الباب يتعطّل أثناء الإغلاق. يمكنك إرسال إشعار متابعة باستخدام errorCode:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "door-device-id": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "follow-up-token-1"
            }
          }
        }
      },
      "states": {
        "door-device-id": {
          "openPercent": 70
        }
      }
    }
  }
}

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

لمزيد من المعلومات وerrorCodes التفصيلية، يُرجى الاطّلاع على المستندات المرجعية حول الأخطاء والاستثناءات.