الأخطاء والاستثناءات

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

الأخطاء

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

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

عندما يكون أحد الأجهزة غير متصل بالإنترنت، عليك الإبلاغ عن {"online": false} لالإبلاغ عن الحالة في غضون 5 دقائق من رصد سلوك الجهاز.

باختصار:

• خطأ على مستوى شامل: تظهر جميع الأجهزة في الاستجابة الخطأ نفسه
• خطأ على المستوى المحلي: استجابة مختلطة تتضمّن حالات خطأ ونجاح

الأخطاء على المستوى العام

يوضّح المقتطف التالي من تنسيق JSON كيفية عرض الأخطاء على مستوى عام في استجابة QUERY أو EXECUTE.

مثال على الخطأ deviceOffline على مستوى الحساب بسبب عدم اتصال المحور بالشبكة:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

مثال على الخطأ inSoftwareUpdate على مستوى الحساب الشامل بسبب تعديل بيانات المحور:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "inSoftwareUpdate",
    "status" : "ERROR"
  }
}

الأخطاء على مستوى الجهاز

استجابة QUERY

يوضِّح المقتطف التالي من ملف JSON كيفية عرض الأخطاء على مستوى الجهاز في استجابة QUERY.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

استجابة EXECUTE

يوضِّح المقتطف التالي من ملف JSON كيفية عرض الأخطاء على مستوى الجهاز في استجابة EXECUTE.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "device-id-2"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      }
    ]
  }
}

الإشعارات التي تحتوي على أخطاء

إشعار استباقي

يوضّح المقتطف التالي من ملف JSON كيفية الإبلاغ عن أخطاء على مستوى الجهاز في إشعار استباقي.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

ردّ متابعة

يوضّح المقتطف التالي من ملف JSON كيفية الإبلاغ عن الأخطاء على مستوى الجهاز في استجابة متابعة.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "PLACEHOLDER"
            }
          }
        }
      }
    }
  }
}

قائمة الأخطاء

ستؤدي الأخطاء التالية إلى إنشاء ميزة تحويل النص إلى كلام المرتبطة بها على الجهاز.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isArmed": true,
        "currentArmLevel": "L2",
        "currentStatusReport": [{
          "blocking": false,
          "deviceTarget": "sensor_id1",
          "priority": 0,
          "statusCode": "deviceOpen"
        }]
      }
    }]
  }
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",
        "currentStatusReport": [{
            "blocking": true,
            "deviceTarget": "device-id-1",
            "priority": 0,
            "statusCode": "lowBattery"
          },
          {
            "blocking": true,
            "deviceTarget": "front_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "deviceTarget": "back_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          }
        ]
      }
    }
  }
}