رسیدگی به خطاها و استثناها

وقتی دستگاه‌ها یا درخواست‌ها آنطور که انتظار می‌رود کار نمی‌کنند، مهم است که مدیریت خطا و ارتباط خوبی را برای کاربران خود فراهم کنید تا آنها بفهمند چه اتفاقی افتاده است و در صورت امکان، چگونه آن را اصلاح کنند. حتماً سناریوهای احتمالی خرابی و نحوه واکنش دستگاه خود را در نظر بگیرید: اگر کاربری یک کار در حال انجام را قطع کند چه می‌شود؟ اگر کاربری در حالی که آفلاین است از دستگاهی درخواست عملی کند چه می‌شود؟ برنامه‌ریزی برای این مشکلات و کمک به کاربر برای بازیابی آنها می‌تواند از ناامیدی کاربر جلوگیری کند و تجربه‌ای با کیفیت بالاتر برای دستگاه‌های شما ایجاد کند.

این راهنما چند نمونه از پاسخ‌های intent را ارائه می‌دهد که خطاها را مدیریت می‌کنند. برای بررسی مقادیر معتبر errorCode برای خطاها و استثنائات، به بخش خطاها و استثنائات مراجعه کنید.

مثال ۱: پاسخ خطا برای EXECUTE قصد (intent)

یک کاربر نهایی دو چراغ هوشمند در اتاق نشیمن خود نصب کرده است. کاربر دستور "روشن کردن چراغ‌های اتاق نشیمن" را صادر می‌کند و گوگل یک دستور EXECUTE به URL شما ارسال می‌کند. شما متوجه شدید که دستگاه‌های کاربر آفلاین و غیرقابل کنترل هستند، بنابراین دستور شما یک پاسخ EXECUTE با status ERROR و errorCode deviceOffline برمی‌گرداند.

این مثال نحوه‌ی برگرداندن یک پاسخ EXECUTE با یک errorCode از یک دستگاه سبک را همانطور که قبلاً توضیح داده شد، نشان می‌دهد:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "light-device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "light-device-id-2"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

Google Assistant پس از دریافت پاسخ، به کاربر پیام « دستگاه در حال حاضر در دسترس نیست» را نشان می‌دهد. به یاد داشته باشید که پس از ارسال errorCode deviceOffline در پاسخ EXECUTE ، همچنان باید وضعیت آفلاین را برای دستگاه‌های موجود در حالت گزارش ارسال کنید.

مثال ۲: استثنای غیر مسدودکننده برای قصد EXECUTE

یک کاربر سعی می‌کند قفل هوشمند درب ورودی خود را با استفاده Assistant قفل کند. شما می‌توانید با موفقیت قفل آنها را کنترل کنید، اما متوجه می‌شوید که باتری دستگاه کم است، بنابراین درخواست شما یک پاسخ EXECUTE با status SUCCESS و exceptionCode lowBattery برمی‌گرداند.

این مثال نحوه ارسال پاسخ EXECUTE با یک exceptionCode از یک دستگاه قفل شده را همانطور که قبلاً توضیح داده شد، نشان می‌دهد:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["lock-device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

Assistant پس از دریافت پاسخ، به کاربر پیام «باتری دستگاه کم است» را نشان می‌دهد.

مثال ۳: اعلان‌های خطای پیشگیرانه

در برخی موارد، هشدار دادن به کاربران در مورد خطا می‌تواند مفید باشد، به خصوص برای عملکردهایی که کاربران انتظار دارند به طور خودکار انجام شوند. برای ویژگی‌هایی که از اعلان‌های پیشگیرانه پشتیبانی می‌کنند، اگر اعلان‌های پیشگیرانه smart home را پیاده‌سازی کرده باشید، می‌توانید به صورت پیشگیرانه در هنگام بروز خطا به کاربر اطلاع دهید.

یک خشک‌کن هوشمند در حال کار است و قبل از اتمام چرخه، شخصی در را باز می‌کند. می‌توانید متد reportStateAndNotifications از API Google Home Graph را فراخوانی کنید تا یک اعلان پیشگیرانه با errorCode ارسال شود:

این مثال نحوه ارسال یک اعلان پیشگیرانه با errorCode از یک دستگاه خشک‌کن را همانطور که قبلاً توضیح داده شد، نشان می‌دهد:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "dryer-device-id": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      },
      "states": {
        "dryer-device-id": {
          "isRunning": false,
          "isPaused": true
        }
      }
    }
  }
}

Assistant پس از دریافت اعلان، به کاربر پیام «درب دستگاه باز است» را می‌دهد. می‌توانید وضعیت‌های مربوط به دستگاه را همراه با اعلان‌ها در همان فایل ارسال کنید.

مثال ۴: اطلاع‌رسانی پیگیری

برای دستورات trait که از اعلان‌های پیگیری پشتیبانی می‌کنند، می‌توانید در صورت بروز خطا یا استثنا، یک اعلان پیگیری برای کاربر ارسال کنید، البته اگر اعلان‌های پیگیری smart home را پیاده‌سازی کرده باشید.

کاربر دستور بستن درب گاراژ خود را صادر می‌کند، اما درب هنگام بسته شدن گیر می‌کند. می‌توانید با استفاده از errorCode یک اعلان پیگیری ارسال کنید:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "door-device-id": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "follow-up-token-1"
            }
          }
        }
      },
      "states": {
        "door-device-id": {
          "openPercent": 70
        }
      }
    }
  }
}

Assistant پس از دریافت اعلان، به کاربر پیام « دستگاه دچار مشکل شده است» را نشان می‌دهد. می‌توانید وضعیت دستگاه مربوطه را با اعلان‌هایی در همان فایل ارسال کنید.

برای اطلاعات بیشتر و جزئیات errorCodes ، به مستندات مرجع خطاها و استثنائات مراجعه کنید.