Hataları ve istisnaları yönetme

Cihazlar veya istekler beklendiği gibi çalışmadığında kullanıcılarınıza iyi bir hata işleme ve iletişim sağlanması, bu sayede neler olduğunu ve nasıl düzeltilebileceğini anlamaları önemlidir. Olası hata senaryolarını ve cihazınızın nasıl tepki vereceğini iyi düşünün: Kullanıcı devam eden bir görevi yarıda keserse ne olur? Kullanıcı çevrimdışıyken bir cihazdan işlem isterse ne olur? Bu sorunların planlanması 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 yüksek kaliteli bir deneyim oluşturur.

Bu kılavuzda, hataları işleyen intent yanıtları için bazı örnekler verilmiştir. 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ı

Son kullanıcının oturma odasında yüklü iki akıllı ışığı var. Kullanıcı, "oturma odası ışıklarını aç" komutu 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 edilemediğini bulduğunuzda, karşılamanızın status ERROR ve errorCode deviceOffline ile EXECUTE yanıtı döndürmesi.

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"
      }
    ]
  }
}

Google Assistant, yanıtı aldıktan sonra "cihaz şu anda kullanılamıyor" istemini gösterir. 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 amacı için engelleyici olmayan istisna

Bir kullanıcı, Assistant kullanarak 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, karşılamanız status ve exceptionCode lowBattery ile EXECUTE yanıtı döndürür.SUCCESS

Bu örnekte, daha önce açıklandığı gibi kilit cihazından exceptionCode ile EXECUTE yanıtının 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 "cihazın pili düşük" mesajını gösterir.

3. Örnek: Proaktif hata bildirimleri

Bazı durumlarda, özellikle kullanıcıların otomatik olarak tamamlamasını bekleyen işlevler için kullanıcıları bir hata konusunda uyarmak yararlı olabilir. Proaktif bildirimleri destekleyen özellikler için smart home proaktif bildirimleri uyguladıysanız kullanıcıyı proaktif bir şekilde bilgilendirebilirsiniz.

Akıllı kurutucu çalışıyor ve biri çember 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 bir kurutma makinesinden 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 kullanıcıya "cihaz kapısı açıldı" mesajını gösterir. İlgili cihaz durumlarını, aynı yükteki bildirimlerin yanında gönderebilirsiniz.

4. Örnek: Takip bildirimi

smart home Takip bildirimlerini uyguladıysanız bir hata veya istisna oluşurken kullanıcıya takip bildirimi gönderebilirsiniz.

Kullanıcı garaj kapısını kapatma komutu verir, ancak kapı kapanırken kapı sıkışmış. 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ıdan "cihaz sıkıştı" uyarısını 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.