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

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

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

المثال 1: استجابة الخطأ لهدف EXECUTE

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

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

مُجفّف ذكي قيد التشغيل، وفتح أحد الأشخاص الباب قبل انتهاء الدورة. يمكنك استدعاء طريقة واجهة برمجة التطبيقات Google Home Graph reportStateAndNotifications لإرسال إشعار استباقي باستخدام 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، يمكنك مراجعة المستندات المرجعية الأخطاء والاستثناءات.