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

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

{
  "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"
          }
        ]
      }
    }
  }
}