デバイスやリクエストが想定どおりに機能しない場合は、発生したエラーの内容と修正方法をユーザーが理解できるように、エラー処理とユーザー コミュニケーションを適切に行うことが重要です。考えられる障害シナリオと、それに対するデバイスの応答方法を考えてください。ユーザーが進行中のタスクを中断した場合はどうなるでしょうか。デバイスがオフラインのときにユーザーがデバイスに対してアクションをリクエストした場合はどうなりますか？これらの問題に備え、ユーザーが回復できるように支援することで、ユーザーの不満を防ぎ、デバイスのエクスペリエンスの質を高めることができます。
このガイドでは、エラーを処理するインテント レスポンスの例をいくつか示します。エラーと例外について有効な 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 will prompt the user with "the device are
not available right now" after receiving the response. Remember that you still
need to send offline state for devices in report state after sending
errorCode deviceOffline in EXECUTE response.
例 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 proactive notifications. を実装すればエラーの発生中にユーザーに予防的に通知できます。
スマート乾燥機の稼働中、サイクルが終了する前に誰かが扉を開けました。Google Home Graph API
reportStateAndNotifications method to send a proactive notification with an
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 の詳細については、エラーと例外のリファレンス ドキュメントをご覧ください。