デバイスやリクエストが想定どおりに動作しない場合は、適切なエラー処理とユーザーへのコミュニケーションを提供して、何が起こったのか、可能であれば修正方法を理解してもらうことが重要です。考えられる障害シナリオと、デバイスがどのように対応すべきかを十分に検討してください。たとえば、ユーザーが進行中のタスクを中断した場合はどうなるでしょうか。デバイスがオフラインのときにユーザーがデバイスにアクションをリクエストした場合はどうなりますか？こうした問題に備え、ユーザーが問題を解決できるようにすることで、ユーザーの不満を回避し、デバイスの品質を高めることができます。
このガイドでは、エラーを処理するインテント レスポンスの例をいくつか示します。エラーと例外の有効な errorCode 値については、エラーと例外をご覧ください。
例 1: EXECUTE インテントのエラー レスポンス
エンドユーザーがリビングルームに 2 つのスマートライトを設置しています。ユーザーが「リビングの照明を点けて」というコマンドを発行すると、Google はフルフィルメント URL に EXECUTE インテントを送信します。しかし、ユーザーのデバイスがオフラインになっていて制御できないことがわかり、フルフィルメントから status ERROR と errorCode deviceOffline を含む EXECUTE レスポンスが返されました。
この例では、前述のように、照明デバイスから errorCode を含む EXECUTE レスポンスを返す方法を示します。
{ "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 を送信した後も、Report State でデバイスのオフライン状態を送信する必要があります。
例 2: EXECUTE インテントの非ブロッキング例外
ユーザーが Assistant を使用して玄関のスマートロックをロックしようとしています。ロックを正常に制御できましたが、デバイスのバッテリー残量が少ないことがわかり、フルフィルメントから status SUCCESS と exceptionCode lowBattery を含む EXECUTE レスポンスが返されました。
次の例は、前述のように、ロックデバイスから exceptionCode を含む EXECUTE レスポンスを送信する方法を示しています。
{ "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 の詳細については、エラーと例外のリファレンス ドキュメントをご覧ください。