Hataları ve istisnaları işleme

Cihazlar veya istekler beklendiği gibi çalışmadığında, kullanıcılarınıza iyi bir hata işleme ve iletişim sağlamanız önemlidir. Böylece kullanıcılarınız ne olduğunu ve mümkün olduğunda nasıl düzelteceklerini anlayabilir. Olası hata senaryolarını ve cihazınızın nasıl yanıt vermesi gerektiğini dikkatlice düşünün: Kullanıcı, devam eden bir görevi kesintiye uğratırsa ne olur? Kullanıcı, çevrimdışı durumdaki bir cihazdan işlem isteğinde bulunursa ne olur? Bu sorunları planlamak ve kullanıcılarınızın bu sorunlardan kurtulmasına yardımcı olmak, kullanıcıların hayal kırıklığına uğramasını önleyebilir ve cihazlarınız için daha kaliteli bir deneyim oluşturabilir.

Bu kılavuzda, hataları işleyen amaç yanıtlarına ilişkin bazı örnekler verilmektedir. Hata ve istisnalar için geçerli errorCode değerlerini incelemek üzere Hatalar ve istisnalar bölümüne bakın.

1. örnek: EXECUTE amacı için hata yanıtı

Bir son kullanıcının oturma odasında iki akıllı ışık yüklü. Kullanıcı "oturma odasının ışıklarını aç" komutunu veriyor ve Google, EXECUTE intent'ini karşılama URL'nize gönderiyor. Kullanıcının cihazlarının çevrimdışı ve kontrol edilemez olduğunu tespit ettiğiniz için karşılamanız EXECUTE yanıtını status ERROR ve errorCode deviceOffline ile birlikte döndürüyor.

Bu örnekte, daha önce açıklandığı gibi, ışıklı bir cihazdan EXECUTE yanıtının errorCode ile nasıl döndürüleceği gösterilmektedir:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "light-device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "light-device-id-2"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

Google Assistant, yanıtı aldıktan sonra kullanıcıya "Cihaz şu anda kullanılamıyor" istemini gösteriyor. EXECUTE yanıtında errorCode deviceOffline gönderdikten sonra rapor durumundaki cihazlar için çevrimdışı durumu göndermeniz gerektiğini unutmayın.

2. örnek: EXECUTE amaçlı, engelleyici olmayan istisna

Bir kullanıcı, Assistant kullanarak ön kapısındaki akıllı kilidi kilitlemeye çalışıyor. Kilitlerini başarıyla kontrol edebilirsiniz ancak cihazın pilinin düşük olduğunu fark edersiniz. Bu nedenle, karşılamanız EXECUTE yanıtını status SUCCESS ve exceptionCode lowBattery ile birlikte döndürür.

Bu örnekte, daha önce açıklandığı gibi kilitli bir cihazdan EXECUTE yanıtının exceptionCode ile nasıl gönderileceği gösterilmektedir:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["lock-device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

Assistant, yanıtı aldıktan sonra kullanıcıya "Cihazın pili azaldı" mesajını gösterir.

3. örnek: Proaktif hata bildirimleri

Bazı durumlarda, özellikle kullanıcıların otomatik olarak tamamlanmasını beklediği işlevlerde kullanıcıları bir hataya karşı uyarmak faydalı olabilir. smart home Proaktif bildirimleri uyguladıysanız proaktif bildirimleri destekleyen özelliklerde hata oluştuğunda kullanıcıyı proaktif olarak bilgilendirebilirsiniz.

Akıllı bir kurutma makinesi çalışırken birisi program bitmeden kapıyı açarsa Google Home Graph API'sinin reportStateAndNotifications yöntemini çağırarak errorCode ile proaktif bildirim gönderebilirsiniz:

Bu örnekte, daha önce açıklandığı gibi bir kurutma makinesi cihazından errorCode içeren proaktif bir bildirimin nasıl gönderileceği gösterilmektedir:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "dryer-device-id": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      },
      "states": {
        "dryer-device-id": {
          "isRunning": false,
          "isPaused": true
        }
      }
    }
  }
}

Assistant, bildirimi aldıktan sonra kullanıcıya "Cihazın kapağı açıldı" istemini gösterir. İlgili cihaz durumlarını aynı yükteki bildirimlerle birlikte gönderebilirsiniz.

4. örnek: Takip bildirimi

Takip bildirimlerini destekleyen özellik komutları için, hata veya istisna oluştuğunda kullanıcıya takip bildirimi gönderebilirsiniz. Bunun için smart home takip bildirimlerini uygulamanız gerekir.

Bir kullanıcı garaj kapısını kapatma komutu veriyor ancak kapı kapanırken sıkışıyor. errorCode ile takip bildirimi gönderebilirsiniz:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "door-device-id": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "follow-up-token-1"
            }
          }
        }
      },
      "states": {
        "door-device-id": {
          "openPercent": 70
        }
      }
    }
  }
}

Assistant, bildirimi aldıktan sonra kullanıcıya "Cihaz sıkıştı" istemini gösterir. İlgili cihaz durumlarını aynı yükteki bildirimlerle birlikte gönderebilirsiniz.

Daha fazla bilgi ve ayrıntılı errorCodes için Hatalar ve istisnalar referans belgelerine bakın.