Error dan pengecualian

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

Error

Anda akan menampilkan kode error saat suatu masalah menyebabkan permintaan eksekusi atau kueri gagal. Misalnya, jika kunci pintu macet dan tidak dapat dikunci atau dibuka kuncinya, error tentang status ini harus ditampilkan kepada pengguna.

Kode error dapat disertakan di tingkat perangkat atau tingkat global. Misalnya, jika pengguna memiliki banyak lampu dari satu penyedia dan mereka dikontrol oleh sebuah hub, saat pengguna meminta untuk mematikan semua lampu, penyedia dapat menampilkan error tingkat perangkat jika satu lampu offline, atau error tingkat global jika seluruh hub offline dan tidak ada lampu yang dapat dikontrol. Jika semua perangkat sedang offline, tidak ada perbedaan antara penggunaan error tingkat global atau tingkat perangkat. 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 kasus error dan berhasil

Error tingkat global

Cuplikan JSON berikut menunjukkan cara Anda menampilkan error tingkat global dalam respons QUERY atau EXECUTE.

Contoh error tingkat global deviceOffline karena hub sedang offline:

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

Contoh error tingkat global inSoftwareUpdate karena hub ini sedang diupdate:

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

Error tingkat perangkat

Respons QUERY

Cuplikan JSON berikut ini menunjukkan cara Anda menampilkan error tingkat perangkat dalam respons 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 Anda menampilkan error tingkat perangkat dalam respons EXECUTE.

{
  "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 yang berisi 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"
          }
        }
      }
    }
  }
}

Tindak lanjuti respons

Cuplikan JSON berikut menunjukkan cara Anda melaporkan error tingkat perangkat dalam respons 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 pemberitahuan yang terkait dengan perintah. Perintah bisa berhasil atau gagal.

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

Misalnya, jika layar lint pengering penuh, pengguna masih dapat memulai pengering, tetapi Anda mungkin ingin memperingatkan pengguna tentang status ini. Demikian pula, jika baterai perangkat lemah dan tidak kosong, Anda masih dapat menjalankan perintah, tetapi harus memberi tahu bahwa baterai perangkat lemah.

Jika perintah gagal karena pengecualian, statusnya harus menjadi "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 yang menggunakan StatusReport

Contoh ini 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.