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

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

يقدِّم هذا الدليل بعض الأمثلة لاستجابات النية التي تعالج الأخطاء. راجِع الأخطاء والاستثناءات لمراجعة قيم 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 API 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، يمكنك الاطّلاع على المستندات المرجعية الأخطاء والاستثناءات.