Menangani error dan pengecualian

Saat perangkat atau permintaan tidak berfungsi seperti yang diharapkan, penting untuk menyediakan penanganan dan komunikasi kesalahan yang baik untuk pengguna Anda sehingga mereka memahami yang terjadi, dan bila memungkinkan, bagaimana memperbaikinya. Pastikan Anda mempertimbangkan dengan baik skenario kegagalan yang mungkin terjadi dan cara perangkat merespons: Bagaimana jika pengguna mengganggu tugas yang sedang berlangsung? Bagaimana jika pengguna meminta tindakan dari perangkat saat offline? Merencanakan masalah ini dan membantu pengguna Anda pulih dari mereka dapat menghindari frustrasi pengguna dan menciptakan pengalaman berkualitas lebih tinggi untuk perangkat Anda.

Panduan ini menyediakan beberapa contoh respons intent yang menangani error. Lihat Error dan pengecualian untuk tinjau nilai errorCode yang valid untuk mengetahui error dan pengecualian.

Contoh 1: Respons error untuk intent EXECUTE

Pengguna akhir memiliki dua lampu smart dan dipasang di ruang tamu. Pengguna mengeluarkan perintah "nyalakan lampu ruang tamu" dan Google mengirimkan EXECUTE intent ke URL pemenuhan Anda. Anda mendapati bahwa perangkat pengguna sedang offline dan tidak dapat dikontrol, sehingga fulfillment Anda menampilkan respons EXECUTE dengan status ERROR dan errorCode deviceOffline.

Contoh ini menunjukkan cara menampilkan respons EXECUTE dengan errorCode dari perangkat ringan seperti yang dijelaskan sebelumnya:

{
  "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 akan meminta pengguna memasukkan "perangkat tidak tersedia saat ini" setelah menerima respons. Ingatlah bahwa Anda masih harus mengirim status offline untuk perangkat dalam status laporan setelah dikirim errorCode deviceOffline dalam respons EXECUTE.

Contoh 2: Pengecualian yang tidak memblokir untuk intent EXECUTE

Pengguna mencoba mengunci smart lock di pintu depan menggunakan perangkat dengan Assistant. Anda dapat berhasil mengontrol kunci mereka tetapi Anda mendapati bahwa baterai perangkat rendah, sehingga fulfillment Anda menampilkan EXECUTE dengan status SUCCESS dan exceptionCode lowBattery.

Contoh ini menunjukkan cara mengirim respons EXECUTE dengan exceptionCode dari perangkat kunci seperti yang dijelaskan sebelumnya:

{
  "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 akan menampilkan pesan "perangkat memiliki hampir habis baterai" setelah menerima respons.

Contoh 3: Notifikasi error proaktif

Dalam beberapa kasus, akan sangat membantu untuk memperingatkan pengguna tentang kesalahan, terutama untuk fungsi yang diharapkan pengguna untuk diselesaikan secara otomatis. Untuk sifat yang mendukung pemberitahuan proaktif, Anda dapat secara proaktif memberi tahu pengguna saat terjadi error jika Anda telah menerapkan smart home notifikasi proaktif.

Pengering smart sedang berjalan, dan seseorang membuka pintu sebelum siklus selesai. Anda dapat memanggil Google Home Graph API Metode reportStateAndNotifications untuk mengirim notifikasi proaktif dengan errorCode:

Contoh ini menunjukkan cara mengirim notifikasi proaktif dengan errorCode dari perangkat pengering seperti yang dijelaskan sebelumnya:

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 akan memberikan prompt kepada pengguna dengan "pintu device adalah dibuka" setelah menerima notifikasi. Anda dapat mengirimkan status perangkat bersama notifikasi dalam payload yang sama.

Contoh 4: Notifikasi tindak lanjut

Untuk perintah ciri yang mendukung notifikasi tindak lanjut, Anda dapat mengirim pemberitahuan tindak lanjut kepada pengguna ketika terjadi kesalahan atau pengecualian, jika Anda telah menerapkan smart home notifikasi tindak lanjut.

Seorang pengguna memberikan perintah untuk menutup pintu garasinya, tetapi pintunya macet sembari menutup. Anda dapat mengirim notifikasi lanjutan dengan 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 akan meminta pengguna memasukkan "perangkat macet" setelah menerima notifikasi. Anda dapat mengirimkan status perangkat dengan notifikasi dalam payload yang sama.

Untuk informasi selengkapnya dan errorCodes yang mendetail, lihat Error dan pengecualian dokumentasi referensi.