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

l10n

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

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