Hatalar ve istisnalar

Bu dokümanda, akıllı ev cihazları için resmi olarak desteklenen hatalar ve istisnalar listelenmektedir. Lütfen belirli bir komut veya cihaz durumuyla ilgili sorunlar konusunda Google Asistan'ın son kullanıcıları uyarması için amaçlanan yanıtta ya da bildirimlerde bu hata ve istisna kodlarını kullanın. Yanıtta yanlış biçimlendirme veya errorCode varsa Google Asistan kullanıcılara genel bir hata mesajı verir, örneğin, "Maalesef cihaz şu anda kullanılamıyor."

Hatalar

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

Hata kodları cihaz düzeyinde veya genel düzeyde eklenebilir. Örneğin, kullanıcı bir sağlayıcıdan gelen çok sayıda ışık varsa ve bu merkez bir merkez tarafından kontrol ediliyorsa kullanıcı tüm ışıklarını kapatmak istediğinde, tek bir ışık çevrimdışıysa sağlayıcı cihaz düzeyinde hata, tüm merkezi çevrimdışıysa ve ışıklar kontrol edilemiyorsa genel düzeyde hata döndürebilir. Tüm cihazlar çevrimdışıysa genel düzeyde veya cihaz düzeyinde hatalar arasında fark yoktur. Bir cihaz çevrimdışıyken deviceOffline hata kodunu döndürseniz bile reportState'te {"online": false} durumunu bildirmeniz gerekir.

Özet olarak:

• Genel düzeyde hata: Yanıttaki tüm cihazlar aynı hataya sahip
• Yerel düzeyde hata: hata ve başarı durumlarıyla karışık yanıt

Genel düzeyde hatalar

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

Merkezden kaynaklanan küresel düzeyde hata deviceOffline örneği:

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

Merkez nedeniyle inSoftwareUpdate düzeyindeki genel hata örneği güncelleniyor:

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

YürütME yanıtı

Aşağıdaki JSON snippet'inde, EXECUTE yanıtında cihaz düzeyinde 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
        }
      }
    ]
  }
}

Hatalı bildirimler

Proaktif bildirim

Aşağıdaki JSON snippet'inde, proaktif bildirimde cihaz düzeyindeki hataları 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, takip yanıtında cihaz düzeyinde hataları nasıl bildirebileceğ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 ilgili sorun veya uyarı olduğunda bir istisna döndürmeniz gerekir. Komut başarılı veya başarısız olabilir.

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

Örneğin, kurutucu tüy kalem ekranı doluysa kullanıcı yine de kurutma makinesini başlatabilir, ancak kullanıcıyı bu durum hakkında uyarmak isteyebilirsiniz. Benzer şekilde, cihazın pili boşken pili bitse bile bir komut çalıştırabilirsiniz, ancak cihazın pilinin azaldığını bildirmelisiniz.

Komut, istisnalar nedeniyle başarısız olursa durum "EXCEPTIONS" olmalıdır ve istisnalar StatusReport özelliği kullanılarak bildirilmelidir.

Hedef cihazla ilgili engelleyici olmayan istisna (SUCCESS)

Bu örnek, kapıyı kilitlemek içindir:

Ön kapı kilidinin pili az. Ö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"
      }
    }]
  }
}

Durum Raporu'nu kullanan başka bir cihazla ilgili engelleyici olmayan istisna (SUCCESS)

Bu örnek, bir güvenlik sisteminin etkinleştirilmesi içindir: Tamam, güvenlik sistemini etkinleştiriyoruz. Ö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 kullanarak başka bir cihazla ilgili istisnayı engelleme

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