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

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

يقدِّم هذا الدليل بعض الأمثلة على الردود حسب النية بالشراء التي تعالج الأخطاء. راجِع الأخطاء والاستثناءات لمراجعة قيم 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 will prompt the user with "the device are not available right now" after receiving the response. Remember that you still need to send offline state for devices in report state after sending errorCode deviceOffline in EXECUTE response.

مثال 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 proactive notifications.

فِيهْ مُجَفِّفْ ذَكِي شَغَّالْ وِفَتْحْ شَخْصْ بَابِ الْبَابْ قَبْلِ انْتِهَاءِ الدَّوْرَة. يمكنك الاتصال بـ Google Home Graph API reportStateAndNotifications method to send a proactive notification with an 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 التفصيلية، يمكنك الاطّلاع على الوثائق المرجعية الأخطاء والاستثناءات.