Hatalar ve istisnalar

Bu dokümanda, akıllı ev cihazları için resmi olarak desteklenen hatalar ve istisnalar listelenmektedir. Lütfen verilen bu hata ve istisna kodlarını intent yanıtında veya uyguladıysanız bildirimlerde kullanın. Böylece Google Asistan, belirli bir komut veya cihaz durumuyla ilgili sorunlar konusunda son kullanıcıları uyarır. Yanıtta yanlış biçimlendirme veya errorCode bulunuyorsa 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 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, kullanıcı bir sağlayıcıdan çok sayıda ışığı kullanıyorsa ve bir merkez tarafından kontrol ediliyorsa kullanıcı tüm ışıklarını kapatmak istediğinde sağlayıcı, tek bir ışığın çevrimdışı olması durumunda cihaz düzeyinde bir hata veya hub'ın tamamı çevrimdışıysa ve ışık kontrol edilemiyorsa genel düzeyde bir hata döndürebilir. Tüm cihazlar çevrimdışıysa genel veya cihaz düzeyinde hatalar arasında fark yoktur. Bir cihaz çevrimdışı olduğunda deviceOffline hata kodunu döndürseniz bile reportState öğesinde {"online": false} durumunu bildirmeniz gerekir.

Özet olarak:

• Genel düzeyde hata: yanıttaki tüm cihazlarda aynı hata bulunuyor
• Yerel düzeyde hata: hata ve başarı durumlarıyla karışık yanıt

Genel düzeydeki hatalar

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

Hub'dan kaynaklanan genel düzeydeki deviceOffline hatasının örneği çevrimdışıdır:

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

Hub'ın güncellenmesinden kaynaklanan inSoftwareUpdate genel düzeydeki hata örneği:

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

Cihaz düzeyindeki 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"
      }
    }
  }
}

Yanıtı UYGULAMA

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

Hata içeren bildirimler

Proaktif bildirim

Aşağıdaki JSON snippet'inde, proaktif bir bildirimde cihaz düzeyindeki hataları nasıl raporladığınız 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, bir takip yanıtında cihaz düzeyindeki hataları nasıl raporladığınız 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 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 = "BAŞARILI") 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 ekranı doluysa kullanıcı yine de kurutma makinesini çalıştırabilir. Ancak kullanıcıyı bu durum hakkında uyarmak isteyebilirsiniz. Benzer şekilde, bir cihazın pil seviyesi boş ve düşük olduğunda da bir komut çalıştırabilirsiniz ancak cihazın pil seviyesinin düşük olduğunu kullanıcıya bildirmeniz gerekir.

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

Hedef cihaz hakkında engellenmeyen istisna (BAŞARILI)

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

Ön kapı kilidinin pil seviyesi 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"
      }
    }]
  }
}

Durum Raporu kullanılan başka bir cihaz hakkında engellenmeyen istisna (BAŞARILI)

Bu örnek, bir güvenlik sistemini devre dışı bırakmak içindir: Tamam, güvenlik sistemi etkinleştiriliyor. Ö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"
        }]
      }
    }]
  }
}

Durum Raporu kullanılarak 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şkilendirilmiş TTS'yi oluşturur.