Hatalar ve istisnalar

Bu dokümanda, akıllı ev cihazları için resmi olarak desteklenen hatalar ve istisnalar listelenmektedir. Lütfen bu hata ve istisna kodlarını amaç yanıtında veya uygulamalarda uygulayın. Böylece Google Asistan, son kullanıcıları belirli bir komut veya cihaz durumuyla ilgili sorunlar hakkında uyarır. 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 kilitlenemiyorsa ya da 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 birçok ışığı varsa ve bir merkez tarafından kontrol ediliyorsa kullanıcı tüm ışıklarını kapatmak istediğinde sağlayıcı, tek bir ışık çevrimdışıysa cihaz düzeyinde bir hata, tüm merkezi çevrimdışıysa ve hiçbir ışık kontrol edilemediyse küresel düzeyde bir hata döndürebilir. Tüm cihazlar çevrimdışıysa global veya cihaz düzeyinde hatalar arasında fark yoktur. Bir cihaz çevrimdışıyken deviceOffline hata kodunu döndürseniz bile reportState içinde {"online": false} durumunu bildirmeniz gerekir.

Özet olarak:

• Genel düzeyde hata: Yanıttaki tüm cihazlar aynı hataya sahip
• Yerel düzeyde hata: Hatalı ve başarılı örnekler içeren karma yanıt

Genel düzeyde hatalar

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

Merkezden dolayı deviceOffline adlı global düzeyde hataya örnek olarak çevrimdışı gösterilebilir:

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

Merkezden dolayı inSoftwareUpdate adlı global düzeyde hataya ilişkin bir örnek 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'i, QUERY yanıtında cihaz düzeyinde hataları nasıl döndürdüğünüzü gösterir.

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

Yürüt

Aşağıdaki JSON snippet'i, HARİÇ TUT yanıtında cihaz düzeyindeki hataları nasıl döndürdüğünüzü gösterir.

{
  "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 bir bildirimle cihaz düzeyindeki 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": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

Takip yanıtı

Aşağıdaki JSON snippet'i, takip yanıtında cihaz düzeyindeki hataları nasıl raporlayacağınızı gösterir.

{
  "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, ilişkili TTS'yi cihazda oluşturur.

İstisnalar

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

Komut başarılı olduysa (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 ekranı doluysa kullanıcı yine de kurutma makinesini başlatabilir ancak bu durum hakkında uyarmak isteyebilirsiniz. Benzer şekilde, boş olmayan ve cihazın boşta kaldığı bir komut çalıştırabilirsiniz, ancak cihazın pilinin az olduğunu bildirmeleri gerekir.

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 (BAŞARILI)

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 cihaz için engellemeyen istisna (SUCCESS)

Bu örnek bir güvenlik sistemini etkinleştirmek 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'u 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.