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

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

تنفيذ الرد

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

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

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

الاستثناءات

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

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

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

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