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

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

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

مثال ۱: پاسخ خطا برای هدف EXECUTE

کاربر نهایی دو چراغ هوشمند در اتاق نشیمن خود نصب کرده است. کاربر فرمان «چراغ‌های پذیرایی را روشن کن» را صادر می‌کند و Google قصد EXECUTE را به نشانی وب انجام تعهد شما ارسال می‌کند. متوجه شدید که دستگاه‌های کاربر آفلاین هستند و قابل‌کنترل نیستند، بنابراین انجام تعهد شما پاسخ 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 اعلان‌های پیش‌کنشی را پیاده‌سازی کرده باشید، می‌توانید هنگام بروز خطا به‌صورت پیش‌کنشی به کاربر اطلاع دهید.

خشک‌کن هوشمند درحال کار است و شخصی قبل‌از پایان چرخه، در را باز می‌کند. می‌توانید روش Google Home Graph API reportStateAndNotifications را برای ارسال اعلان پیش‌کنشی با 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 با پیام‌واره «درب دستگاه باز است» از کاربر می‌خواهد اقدام کند. می‌توانید وضعیت‌های دستگاه مربوطه را همراه با اعلان‌ها در همان بار داده ارسال کنید.

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

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