Error dan pengecualian

Dokumen ini mencantumkan error dan pengecualian yang didukung secara resmi untuk perangkat smart home. Gunakan kode error dan pengecualian yang diberikan ini dalam intent respons, atau dalam notifikasi jika Anda telah menerapkannya, jadi Asisten Google akan memberi tahu pengguna akhir tentang masalah yang terkait dengan perintah atau status perangkat tertentu. Jika respons berisi format yang salah atau errorCode, Asisten Google memberikan pesan error umum kepada pengguna, misalnya, "Maaf, perangkat tidak tersedia saat ini".

Error

Anda harus mengembalikan kode {i>error<i} ketika masalah menyebabkan {i>eksekusi <i}atau permintaan kueri gagal. Misalnya, jika kunci pintu macet dan tidak dapat dikunci atau tidak dikunci, error tentang status ini harus ditampilkan kepada pengguna.

Kode error dapat dilampirkan di tingkat perangkat atau di tingkat global. Misalnya, jika pengguna memiliki banyak lampu dari satu penyedia dan mereka dikendalikan oleh sebuah hub, ketika pengguna meminta untuk mematikan semua lampu, penyedia dapat mengembalikan kesalahan tingkat perangkat jika satu lampu sedang offline, atau kesalahan tingkat global jika seluruh hub mereka {i>offline<i} dan tidak ada lampu yang dapat dikontrol. Jika semua perangkat sedang offline, tidak ada perbedaan antara menggunakan level global atau level perangkat yang sama. Saat perangkat sedang offline, Anda harus melaporkan status {"online": false} di reportState meskipun Anda menampilkan Kode error deviceOffline.

Rangkuman:

• Error tingkat global: semua perangkat dalam respons memiliki error yang sama
• Error tingkat lokal: respons campuran dengan error dan kasus berhasil

Error tingkat global

Cuplikan JSON berikut menunjukkan cara menampilkan error tingkat global di QUERY atau EXECUTE.

Contoh error tingkat global deviceOffline karena hub adalah offline:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

Contoh error tingkat global inSoftwareUpdate karena hub adalah memperbarui:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "inSoftwareUpdate",
    "status" : "ERROR"
  }
}

Error tingkat perangkat

Respons QUERY

Cuplikan JSON berikut menunjukkan cara menampilkan error tingkat perangkat di bagian QUERY.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

MELAKSANAKAN respons

Cuplikan JSON berikut menunjukkan cara menampilkan error tingkat perangkat di bagian MELAKSANAKAN respons.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "device-id-2"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      }
    ]
  }
}

Notifikasi dengan error

Notifikasi proaktif

Cuplikan JSON berikut menunjukkan cara melaporkan error tingkat perangkat dalam notifikasi proaktif.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

Respons selanjutnya

Cuplikan JSON berikut menunjukkan cara melaporkan error tingkat perangkat dalam tindak lanjut.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "PLACEHOLDER"
            }
          }
        }
      }
    }
  }
}

Daftar kesalahan

Error berikut akan menghasilkan TTS terkait di perangkat.

Pengecualian

Anda harus menampilkan pengecualian saat ada masalah atau peringatan yang terkait dengan perintah. Perintah dapat berhasil atau gagal.

Jika perintah berhasil (status = "SUCCESS"), laporkan pengecualian menggunakan ciri StatusReport (untuk perangkat selain target), atau dengan menampilkan exceptionCode yang sesuai (untuk perangkat target).

Misalnya, jika layar lint pengering penuh, pengguna masih bisa memulai pengering, tetapi Anda perlu memperingatkan mereka tentang keadaan ini. Demikian pula, ketika perangkat memiliki daya baterai rendah yang tidak kosong, Anda masih dapat menjalankan perintah tetapi harus memberi tahu mereka bahwa baterai perangkat lemah.

Jika perintah gagal karena pengecualian, statusnya harus "EXCEPTIONS", dan pengecualian harus dilaporkan menggunakan trait StatusReport.

Pengecualian non-pemblokiran (SUCCESS) tentang perangkat target

Contoh ini untuk mengunci pintu:

Daya baterai kunci pintu depan lemah. Mengunci pintu depan.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

Pengecualian non-pemblokiran (SUCCESS) tentang perangkat lain menggunakan StatusReport

Contoh berikut ditujukan untuk mengaktifkan sistem keamanan: Oke, mengaktifkan sistem keamanan. Jendela depan terbuka.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isArmed": true,
        "currentArmLevel": "L2",
        "currentStatusReport": [{
          "blocking": false,
          "deviceTarget": "sensor_id1",
          "priority": 0,
          "statusCode": "deviceOpen"
        }]
      }
    }]
  }
}

Memblokir pengecualian tentang perangkat lain menggunakan StatusReport

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",
        "currentStatusReport": [{
            "blocking": true,
            "deviceTarget": "device-id-1",
            "priority": 0,
            "statusCode": "lowBattery"
          },
          {
            "blocking": true,
            "deviceTarget": "front_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "deviceTarget": "back_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          }
        ]
      }
    }
  }
}

Daftar pengecualian

Pengecualian berikut akan menghasilkan TTS terkait di perangkat.