Hatalar ve istisnalar

Bu dokümanda, akıllı ev cihazları için resmi olarak desteklenen hatalar ve istisnalar listelenmiştir. Google Asistan'ın son kullanıcıları belirli bir komut veya cihaz durumuyla ilgili sorunlar konusunda uyarabilmesi için lütfen intent yanıtında ya da uyguladıysanız bildirimlerde verilen bu hata ve istisna kodlarını kullanın. Yanıt yanlış biçimlendirme veya errorCode içeriyorsa Google Asistan kullanıcılara genel bir hata mesajı gösterir (ör. "Maalesef cihaz şu anda kullanılamıyor").

Hatalar

Bir sorun, yürütme veya sorgu isteğinizin başarısız olmasına neden olduğunda hata kodu döndürmeniz gerekir. Örneğin, bir kapı kilidi sıkışmışsa ve kilitlenemiyor veya kilidi açılamıyorsa kullanıcıya bu durumla ilgili bir hata döndürülmelidir.

Hata kodları cihaz düzeyinde veya genel düzeyde eklenebilir. Örneğin, bir kullanıcının tek bir sağlayıcıdan çok sayıda ışığı varsa ve bunlar bir merkez tarafından kontrol ediliyorsa kullanıcı tüm ışıklarını kapatmasını istediğinde sağlayıcı, tek bir ışık çevrimdışıysa cihaz düzeyinde bir hata, merkezin tamamı çevrimdışıysa ve hiçbir ışık kontrol edilemiyorsa genel düzeyde bir hata döndürebilir. Tüm cihazlar çevrimdışıysa genel düzeyde veya cihaz düzeyinde hata kullanmak arasında fark yoktur.

Bir cihaz çevrimdışıyken cihazın davranışından sonraki 5 dakika içinde {"online": false}'ü Durum Bildir'e bildirmeniz gerekir.

Özet olarak:

• Küresel düzeyde hata: Yanıttaki tüm cihazlarda aynı hata var
• Yerel düzeyde hata: Hata ve başarı durumlarının yer aldığı karma yanıt

Küresel düzeyde hatalar

Aşağıdaki JSON snippet'inde, QUERY veya EXECUTE yanıtında genel düzeyde hataları nasıl döndüreceğiniz gösterilmektedir.

Merkezin çevrimdışı olması nedeniyle global düzeyde deviceOffline hatası örneği:

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

Merkezin güncellenmesi nedeniyle global düzeyde inSoftwareUpdate hatası örneği:

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

Cihaz düzeyinde hatalar

QUERY yanıtı

Aşağıdaki JSON snippet'inde, QUERY yanıtında cihaz düzeyindeki hataları nasıl döndüreceğiniz gösterilmektedir.

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

EXECUTE yanıtı

Aşağıdaki JSON snippet'inde, EXECUTE yanıtında cihaz düzeyindeki hataları nasıl döndüreceğiniz gösterilmektedir.

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

Hata içeren bildirimler

Proaktif bildirim

Aşağıdaki JSON snippet'inde, cihaz düzeyindeki hataları proaktif bir bildirimde nasıl bildireceğiniz gösterilmektedir.

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

Takip yanıtı

Aşağıdaki JSON snippet'inde, cihaz düzeyindeki hataları takip yanıtında nasıl bildireceğiniz gösterilmektedir.

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

Hata listesi

Aşağıdaki hatalar, cihazda ilişkili TTS'yi oluşturur.

İstisnalar

Bir komutla ilişkili bir sorun veya uyarı olduğunda istisna döndürmeniz gerekir. Komut başarılı veya başarısız olabilir.

Komut başarılıysa (status = "SUCCESS") StatusReport özelliğini kullanarak (hedef dışındaki cihazlar için) veya uygun bir exceptionCode döndürerek (hedef cihaz için) istisnaları bildirin.

Örneğin, kurutucu tüy filtresi dolu olsa bile kullanıcı kurutucusunu başlatabilir ancak kullanıcıyı bu durum hakkında uyarmak isteyebilirsiniz. Benzer şekilde, bir cihazın pili boş olmasa da düşükse komutu yine de yürütebilirsiniz ancak cihazın pilinin düşük olduğunu kullanıcıya bildirmeniz gerekir.

Komut istisnalar nedeniyle başarısız olursa durum "EXCEPTIONS" olur ve istisnalar StatusReport özelliği kullanılarak raporlanır.

Hedef cihazla ilgili engellenmeyen istisna (SUCCESS)

Bu örnekte kapının kilitlenmesi gösterilmektedir:

Ön kapı kilidinin pili düşük. Ön kapı kilitleniyor.

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

StatusReport kullanan başka bir cihazla ilgili engellenmeyen istisna (SUCCESS)

Bu örnek, güvenlik sistemini etkinleştirmeyle ilgilidir: Tamam, güvenlik sistemini etkinleştiriyorum. Ön pencere açık.

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

StatusReport kullanan başka bir cihazla ilgili engelleme istisnası

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

İstisna listesi

Aşağıdaki istisnalar, cihazda ilişkili TTS'yi oluşturur.