خطاها و استثنائات

این سند، خطاها و استثنائات پشتیبانی‌شده رسمی برای دستگاه‌های خانه هوشمند را فهرست می‌کند. لطفاً از این کدهای خطا و استثنائات داده‌شده در پاسخ intent یا در اعلان‌ها (در صورت پیاده‌سازی) استفاده کنید، تا دستیار گوگل (Google Assistant) کاربران نهایی را از مشکلات مربوط به یک دستور یا وضعیت دستگاه مطلع کند. اگر پاسخ حاوی قالب‌بندی نادرست یا errorCode باشد، دستیار گوگل یک پیام خطای عمومی به کاربران می‌دهد، به عنوان مثال، "متاسفیم، دستگاه در حال حاضر در دسترس نیست".

خطاها

شما باید زمانی که مشکلی باعث عدم موفقیت در اجرای درخواست یا پرس و جو می‌شود، یک کد خطا را برگردانید. برای مثال، اگر قفل در گیر کرده و نمی‌توان آن را قفل یا باز کرد، باید خطایی در مورد این وضعیت به کاربر برگردانده شود.

کدهای خطا می‌توانند در سطح دستگاه یا در سطح سراسری ضمیمه شوند. برای مثال، اگر کاربری چراغ‌های زیادی از یک ارائه‌دهنده داشته باشد و آنها توسط یک هاب کنترل شوند، وقتی کاربر درخواست خاموش کردن همه چراغ‌های خود را می‌دهد، ارائه‌دهنده ممکن است اگر یک چراغ آفلاین باشد، خطای سطح دستگاه را برگرداند، یا اگر کل هاب آفلاین باشد و هیچ چراغی قابل کنترل نباشد، خطای سطح سراسری را برگرداند. اگر همه دستگاه‌ها آفلاین باشند، تفاوتی بین استفاده از خطاهای سطح سراسری یا سطح دستگاه وجود ندارد.

به طور خلاصه:

• خطای سطح سراسری: تمام دستگاه‌های موجود در پاسخ، خطای یکسانی دارند.
• خطای سطح محلی: پاسخ ترکیبی با موارد خطا و موفقیت

خطاهای سطح جهانی

قطعه کد 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"
  }
}

خطاهای سطح دستگاه

پاسخ پرس و جو

قطعه کد 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 زیر نحوه‌ی برگرداندن خطاهای سطح دستگاه در پاسخ 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 مربوطه را در دستگاه ایجاد می‌کنند.

گزارش وضعیت آنلاین و آفلاین

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

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