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

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

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