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 respons maksud, atau dalam notifikasi jika Anda telah menerapkannya, sehingga 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 akan memberikan pesan error umum kepada pengguna, misalnya, "Maaf, perangkat tidak tersedia saat ini".

Error

Anda harus menampilkan kode error saat masalah menyebabkan permintaan eksekusi atau kueri gagal. Misalnya, jika kunci pintu macet dan tidak dapat dikunci atau dibuka, 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 dikontrol oleh hub, saat pengguna meminta untuk mematikan semua lampunya, 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 offline, tidak ada perbedaan antara penggunaan error tingkat global atau tingkat perangkat.

Rangkuman:

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

Error tingkat global

Cuplikan JSON berikut menunjukkan cara 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 sedang diperbarui:

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

Respons EXECUTE

Cuplikan JSON berikut menunjukkan cara 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 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 lanjutan

Cuplikan JSON berikut menunjukkan cara melaporkan error tingkat perangkat dalam respons lanjutan.

{
  "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.

Pelaporan status online dan offline

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

Pengecualian

Anda harus menampilkan pengecualian jika ada masalah atau pemberitahuan yang terkait dengan perintah. Perintah dapat 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 serat pengering penuh, pengguna masih dapat memulai pengering, tetapi Anda mungkin ingin memperingatkan mereka tentang kondisi ini. Demikian pula, saat baterai perangkat hampir habis tetapi tidak kosong, Anda masih dapat menjalankan perintah, tetapi harus memberi tahu pengguna bahwa baterai perangkat hampir habis.

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

Pengecualian tidak memblokir (BERHASIL) tentang perangkat target

Contoh ini adalah untuk mengunci pintu:

Daya baterai smart lock 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 (BERHASIL) tentang perangkat lain yang menggunakan StatusReport

Contoh ini adalah 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"
        }]
      }
    }]
  }
}

Pengecualian pemblokiran tentang perangkat lain yang 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.