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

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

الأخطاء

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

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

باختصار:

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

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

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

مثال على خطأ على المستوى العام deviceOffline لأنّ الموزع غير متصل بالإنترنت:

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

فيما يلي مثال على خطأ inSoftwareUpdate على المستوى العام بسبب الموزع (hub):

{
  "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) المرتبط على الجهاز.

الاستثناءات

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

إذا تم الأمر بنجاح (الحالة = "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) بشأن جهاز آخر باستخدام 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) المرتبطة على الجهاز.