Hataları ve istisnaları yönetme

Cihazlar veya istekler beklendiği gibi çalışmadığında, ne olduğunu ve mümkünse bunların nasıl düzeltileceğini anlamaları için kullanıcılarınıza iyi bir hata işleme ve iletişim sağlamaları önemlidir. Olası hata senaryolarını ve cihazınızın nasıl tepki vereceğini iyice düşünün: Kullanıcı devam eden bir görevi yarıda keserse ne olur? Kullanıcı çevrimdışıyken bir cihazdan işlem yapılmasını isterse ne olur? Bu sorunları planlamanız ve kullanıcılarınızın bu sorunlardan kurtulmasına yardımcı olmanız, kullanıcıların hayal kırıklığına uğramasını önleyebilir ve cihazlarınız için daha kaliteli bir deneyim sunabilir.

Bu kılavuzda, hataları işleyen amaç yanıtları için bazı örnekler verilmiştir. Hata ve istisnalar için geçerli errorCode değerlerini incelemek amacıyla Hatalar ve istisnalar bölümünü inceleyin.

1. Örnek: EXECUTE niyeti için hata yanıtı

Son kullanıcının iki akıllı ışığı var ve oturma odasında kurulu. Kullanıcı "oturma odası ışıklarını aç" komutunu verir ve Google, sipariş karşılama URL'nize bir EXECUTE niyeti gönderir. Kullanıcının cihazlarının çevrimdışı olduğunu ve kontrol edilemeyeceğini tespit ettiniz. Bu nedenle, sipariş karşılama işlemi status ERROR ve errorCode deviceOffline ile EXECUTE yanıtı döndürüyor.

Bu örnekte, daha önce açıklandığı gibi basit bir cihazdan errorCode ile EXECUTE yanıtının 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"
      }
    ]
  }
}

Yanıt alındıktan sonra Google Assistant, "cihazda şu anda kullanılamadığını" belirtir. EXECUTE yanıtında errorCode deviceOffline gönderdikten sonra rapor durumundaki cihazlar için çevrimdışı durumu yine de göndermeniz gerektiğini unutmayın.

2. Örnek: EXECUTE amacıyla engelleyici olmayan istisna

Kullanıcı, Assistant kullanırken cihazı kullanarak ön kapıdaki akıllı kilidini kilitlemeye çalışıyor. Kilitlerini başarılı bir şekilde kontrol edebilirsiniz, ancak cihazın pilinin az olduğunu görürsünüz. Bu nedenle sipariş karşılama işlemi, status SUCCESS ve exceptionCode lowBattery ile EXECUTE yanıtı döndürür.

Bu örnekte, daha önce açıklandığı gibi bir kilit cihazından exceptionCode ile EXECUTE yanıtı 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, "cihazın pili düşük" yanıtını aldıktan sonra kullanıcıdan bunu yapmasını ister.

3. Örnek: Proaktif hata bildirimleri

Bazı durumlarda, özellikle kullanıcıların otomatik olarak tamamlamasını beklediğiniz işlevler için kullanıcıları bir hata konusunda uyarmak yararlı olabilir. Proaktif bildirimleri destekleyen özelliklerde, smart homeproaktif bildirimleri uyguladıysanız hata meydana gelirken kullanıcıyı proaktif olarak bilgilendirebilirsiniz.

Akıllı kurutucu çalışıyor ve biri döngü bitmeden kapıyı açıyor. errorCode ile proaktif bildirim göndermek için Google Home Graph APIreportStateAndNotifications yöntemini çağırabilirsiniz:

Bu örnekte, daha önce açıklandığı gibi kurutucu bir cihazdan errorCode ile proaktif 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 "cihaz kapağı açık" olan kullanıcıya istem gösterir. İlgili yük durumlarını, aynı yük içindeki bildirimlerle birlikte gönderebilirsiniz.

4. Örnek: Takip bildirimi

smart homeTakip bildirimlerini uyguladıysanız hata veya istisna oluşurken takip bildirimlerini destekleyen özellik komutları için kullanıcıya takip bildirimi gönderebilirsiniz.

Bir kullanıcı garaj kapısını kapatma komutu veriyor ama kapanırken kapı 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 "cihaz sıkışmış" olan kullanıcıdan istem alır. İlgili cihaz durumlarını, aynı yükteki bildirimlerle gönderebilirsiniz.

Daha fazla bilgi ve ayrıntılı errorCodes için Hatalar ve istisnalar referans dokümanına bakın.