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

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

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

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

ผู้ใช้ปลายทางมีหลอดไฟอัจฉริยะ 2 ดวงที่ติดตั้งอยู่ในห้องนั่งเล่น ผู้ใช้ใช้คําสั่ง "เปิดไฟห้องนั่งเล่น" แล้ว Google ส่ง Intent ของ EXECUTE ไปยัง URL Fulfillment คุณพบว่าอุปกรณ์ของผู้ใช้ออฟไลน์และไม่สามารถควบคุมได้ การดําเนินการตามคําสั่งซื้อจึงส่งคืนการตอบกลับ 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 ความตั้งใจ

ผู้ใช้พยายามล็อก Smart Lock ที่ประตูหน้าโดยใช้อุปกรณ์ 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 การแจ้งเตือนเชิงรุก

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

ตัวอย่างที่ 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 โดยละเอียด โปรดดูเอกสารอ้างอิง ข้อผิดพลาดและข้อยกเว้น