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

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

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