デバイスやリクエストが想定したとおりに機能しない場合は、適切なエラー処理とユーザーへの通知を行い、何が起こったのか（可能であればどう修正すべきか）をユーザーが把握できるようにすることが重要です。どのようなエラーが発生する可能性があり、それに対してデバイスからどう応答すべきかを十分に検討してください。実行中のタスクをユーザーが中断したらどうするか、 ユーザーがオフラインのデバイスに対して操作をリクエストしたらどうするかなど、さまざまなシナリオを考えておく必要があります。 これらのエラー処理を適切に計画して復旧を支援することで、デバイスに対するユーザーの不満を解消し、デバイス エクスペリエンスを向上させることができます。
このガイドでは、エラーを処理するインテント レスポンスの例をいくつか示します。エラーと例外の有効な errorCode 値については、エラーと例外をご覧ください。
例 1: EXECUTE インテントのエラー レスポンス
あるエンドユーザーが、2 個のスマートライトをリビングに設置しました。ユーザーが「リビングの電気をつけて」と話しかけ、Google アシスタントが EXECUTE インテントをフルフィルメント URL に送信しました。しかし、ユーザーのデバイスがオフラインになっていて制御できないことがわかり、フルフィルメントから 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 インテントの非ブロッキング例外
あるユーザーが、Google アシスタントを使用して玄関のスマートロックの鍵をかけようとしています。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 の詳細については、
エラーと例外
のリファレンス ドキュメントをご覧ください。