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

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

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

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

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

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