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

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

خطاها

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

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

وقتی دستگاهی آفلاین است، باید {"online": false} را در عرض 5 دقیقه پس از عملکرد دستگاه به گزارش وضعیت گزارش دهید.

به طور خلاصه:

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

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

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