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

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

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

مثال 1: پاسخ خطا برای قصد EXECUTE

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

مثال 2: استثنا غیر مسدود کننده برای قصد 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 پس از دریافت پاسخ از کاربر می‌گوید «باتری دستگاه کم است».

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

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

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

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

مثال 4: اطلاعیه پیگیری

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