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

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

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