จัดการข้อผิดพลาดและข้อยกเว้น

เมื่ออุปกรณ์หรือคำขอทำงานไม่เป็นไปตามที่คาดไว้ คุณควรจัดการข้อผิดพลาดและสื่อสารกับผู้ใช้ให้ดีเพื่อให้ผู้ใช้เข้าใจสิ่งที่เกิดขึ้น และรู้วิธีแก้ไขหากเป็นไปได้ ตรวจสอบว่าคุณได้พิจารณาสถานการณ์ที่อาจเกิดความล้มเหลวและวิธีที่อุปกรณ์ควรตอบสนองแล้ว เช่น จะเกิดอะไรขึ้นหากผู้ใช้ขัดจังหวะงานที่กำลังดำเนินการอยู่ จะเกิดอะไรขึ้นหากผู้ใช้ขอให้ดำเนินการจากอุปกรณ์ขณะที่อุปกรณ์ออฟไลน์ การวางแผนเพื่อรับมือกับปัญหาเหล่านี้และการช่วยให้ผู้ใช้กู้คืนจากปัญหาดังกล่าวจะช่วยหลีกเลี่ยงความไม่พอใจของผู้ใช้และสร้างประสบการณ์การใช้งานอุปกรณ์ที่มีคุณภาพสูงขึ้น

คู่มือนี้มีตัวอย่างการตอบกลับ Intent ที่จัดการข้อผิดพลาด โปรดดู ข้อผิดพลาดและข้อยกเว้นเพื่อ ตรวจสอบค่า errorCode ที่ถูกต้องสำหรับข้อผิดพลาดและข้อยกเว้น

ตัวอย่างที่ 1: การตอบกลับข้อผิดพลาดสำหรับ Intent EXECUTE

ผู้ใช้ปลายทางติดตั้งหลอดไฟอัจฉริยะ 2 หลอดในห้องนั่งเล่น ผู้ใช้ส่งคำสั่ง "เปิดไฟห้องนั่งเล่น" และ Google ส่ง 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

ตัวอย่างที่ 2: ข้อยกเว้นที่ไม่บล็อกสำหรับ Intent 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 จะแจ้งให้ผู้ใช้ทราบว่า "อุปกรณ์แบตเตอรี่เหลือน้อย" หลังจากได้รับการตอบกลับAssistant

ตัวอย่างที่ 3: การแจ้งเตือนข้อผิดพลาดเชิงรุก

ในบางกรณี การแจ้งเตือนผู้ใช้ถึงข้อผิดพลาดอาจเป็นประโยชน์ โดยเฉพาะอย่างยิ่งสำหรับฟังก์ชันที่ผู้ใช้คาดหวังว่าจะดำเนินการโดยอัตโนมัติ สำหรับลักษณะการทำงานที่ รองรับการแจ้งเตือนเชิงรุก คุณสามารถแจ้งเตือนผู้ใช้เชิงรุกขณะเกิด ข้อผิดพลาดได้หากคุณได้ใช้ smart home การแจ้งเตือนเชิงรุก

เครื่องอบผ้าอัจฉริยะกำลังทำงานอยู่ และมีคนเปิดประตูเครื่องก่อนที่รอบการทำงานจะเสร็จสิ้น คุณสามารถเรียกใช้เมธอดของ API Google Home Graph เพื่อส่งการแจ้งเตือนเชิงรุกที่มี errorCode ได้ดังนี้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 โดยละเอียดได้ใน เอกสารอ้างอิง ข้อผิดพลาดและข้อยกเว้น