エラーと例外を処理する

デバイスやリクエストが想定どおりに機能しない場合は、 優れたエラー処理とコミュニケーションを ユーザーに届けることで 可能な限り修正方法を提示しますよく考えてから 考えられる障害シナリオとデバイスの応答方法について どうすればよいでしょうか。ユーザーがデバイスからの操作をリクエストした場合 どうすればよいでしょうかこれらの問題への備えとユーザーの復元のサポート ユーザーのストレスを回避し、質の高いエクスペリエンスを創出できます。 管理できます。

このガイドでは、エラーを処理するインテント レスポンスの例をいくつか示します。詳しくは、 エラーと例外を エラーと例外について有効な errorCode 値を確認してください。

例 1: EXECUTE インテントのエラー レスポンス

あるエンドユーザーが、2 個のスマートライトをリビングに設置しました。ユーザー 「リビングの照明をつけて」というコマンドを発行しましたと Google が EXECUTE を送信しました フルフィルメント URL に追加します。しかし、ユーザーのデバイスがオフラインになっていて制御できないことがわかり、フルフィルメントから status ERRORerrorCode deviceOffline を含む EXECUTE レスポンスが返されました。

この例では、EXECUTE レスポンスを 前述のように、ライトデバイスからの errorCode:

{
  "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 はユーザーに「デバイスは 現在は利用不可」レスポンスを受信したら自動的に処理されます。覚えておいてください。 レポート状態のデバイスについては、送信後にオフライン状態を送信する必要がある EXECUTE レスポンスの errorCode deviceOffline

例 2: EXECUTE インテントの非ブロッキング例外

玄関のドアでスマートロックをロックしようとしているユーザーが、 Assistant。ロックは正常に操作できますが、 デバイスの電池残量が少なくなっているため、フルフィルメントから EXECUTE が返されます。 status SUCCESSexceptionCode lowBattery のレスポンス。

この例では、EXECUTE レスポンスを 前述のように、ロックデバイスからの exceptionCode:

{
  "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 が「デバイスのバッテリー残量が少なくなっています」というメッセージを表示します。 バッテリーレスポンスを受信したら自動的に処理されます。

例 3: パーソナル通知

パーソナル通知を使って事前にエラーを通知し、ユーザーに警告すると効果的な場合があります。たとえば、ユーザーが自動的に完了すると思っている機能に関する通知です。このトレイトは、 プロアクティブな通知のサポートにより、通知が届いても、 このエラーは、smart home を実装している場合に発生します。 パーソナル通知

スマート乾燥機の稼働中、サイクルが終了する前に誰かが扉を開けました。Google Home Graph API を呼び出すことができます。 reportStateAndNotifications メソッドを使用し、 errorCode:

この例では、事前通知を送信する方法を示しています。 errorCode: 前述のように乾燥機から取り出します。

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 が「デバイスのドアは 開いています」確認することもできます。対応する デバイスの状態と通知の両方を同じペイロードで表示できます。

例 4: フォローアップ通知

フォローアップ通知をサポートするトレイト コマンドの場合は、 エラーや例外が発生したときにユーザーにフォローアップ通知を送信する smart home を実装している フォローアップ通知

ユーザーが車庫のドアを閉めるコマンドを出しましたが、ドアが詰まっています 閉じることができます。このような場合は、errorCode でフォローアップ通知を送信できます。

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 が「デバイスは 故障しました」確認することもできます。対応する 複数のデバイス状態を同じペイロードで表示できます。

詳細と errorCodes について詳しくは、以下をご覧ください。 エラーと例外 ご覧ください。