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

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

الأخطاء

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

يمكن إرفاق رموز الخطأ على مستوى الجهاز أو على مستوى عام. على سبيل المثال، إذا كان المستخدم يمتلك العديد من المصابيح من موفر واحد وكان يتم التحكم فيها من خلال موزع، عندما يطلب المستخدم إيقاف كل المصابيح، قد يعرض الموفر خطأ على مستوى الجهاز إذا كان هناك مصباح واحد غير متصل بالإنترنت، أو خطأ على مستوى العالم إذا كان مركزه بالكامل غير متصل بالإنترنت ولا يمكن التحكم في مصابيحه. إذا كانت جميع الأجهزة غير متصلة بالإنترنت، فلا يوجد فرق بين استخدام الأخطاء على مستوى العالم أو الأخطاء على مستوى الجهاز. عندما يكون الجهاز غير متصل بالإنترنت، يجب الإبلاغ عن حالة {"online": false} في reportState حتى إذا عرضت رمز الخطأ deviceOffline.

باختصار:

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

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

يعرض مقتطف 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"
            }
          }
        }
      }
    }
  }
}

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

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

الاستثناءات

يجب عرض استثناء عند وجود مشكلة أو تنبيه مرتبط بأمر. قد ينجح الأمر أو يتعذّر تنفيذه.

إذا كان الأمر ناجحًا (الحالة = "SUCCESS")، يمكنك الإبلاغ عن الاستثناءات باستخدام السمة StatusReport (للأجهزة بخلاف الهدف)، أو من خلال عرض exceptionCode مناسب (للجهاز المستهدف).

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

إذا تعذّر تنفيذ الأمر بسبب الاستثناءات، يجب أن تكون الحالة "EXCEPTIONS"، ويجب الإبلاغ عن الاستثناءات باستخدام السمة StatusReport.

استثناء لا يحظر (SUCCESS) حول الجهاز المستهدف

هذا المثال عن قفل الباب:

البطارية منخفضة. يَتِمُّ الْآنَ إِقْفَالُ الْبَابِ الْأَمَامِي.

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

استثناء غير محظور (SUCCESS) حول جهاز آخر باستخدام StatusReport

هذا المثال مخصص لتسلية نظام أمان: حسنًا، تشغيل جهاز الأمان. النافذة الأمامية مفتوحة.

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

حظر الاستثناء بشأن جهاز آخر باستخدام StatusReport

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

قائمة الاستثناء

وستؤدي الاستثناءات التالية إلى استخدام تقنية تحويل النص إلى كلام (TTS) المرتبطة على الجهاز.