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

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

الأخطاء

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

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

باختصار:

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

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

يوضّح مقتطف JSON التالي كيفية عرض الأخطاء على مستوى العالم في الاستجابة {0}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 التالي طريقة عرض الأخطاء على مستوى الجهاز في استجابة طلب البحث.

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

ردّ مستبعد

يوضِّح مقتطف 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"
            }
          }
        }
      }
    }
  }
}

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

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

الاستثناءات

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

إذا كان الأمر ناجحًا (الحالة = "SUCCESS")، يمكنك الإبلاغ عن الاستثناءات باستخدام السمة 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) حول جهاز آخر باستخدام ReportReport

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

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

حظر استثناء حول جهاز آخر باستخدام ReportReport

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

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

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