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

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

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

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

ผู้ใช้ปลายทางมีหลอดไฟอัจฉริยะ 2 ดวงและติดตั้งในห้องนั่งเล่น ผู้ใช้ ออกคำสั่ง "เปิดไฟห้องนั่งเล่น" และ Google ได้ส่งEXECUTE Intent ของ 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: ข้อยกเว้นแบบไม่บล็อกสำหรับ Intent 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 โดยละเอียด โปรดดูที่ ข้อผิดพลาดและข้อยกเว้น เอกสารอ้างอิง