デバイスやリクエストが想定どおりに機能しない場合は、発生したエラーの内容と、その修正方法をユーザーが理解できるように、適切なエラー処理とコミュニケーションをユーザーに提供することが重要です。考えられる障害シナリオとデバイスの応答方法を確認してください。ユーザーが進行中のタスクを中断した場合はどうなるでしょうか。オフラインのときにユーザーがデバイスからアクションをリクエストした場合はどうなりますか？このような問題をプランニングして、ユーザーが問題を解決できるようにすることで、ユーザーの不満を回避し、デバイスの品質を向上させることができます。
このガイドでは、エラーを処理するインテント レスポンスの例をいくつか示します。エラーと例外の有効な 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 を送信した後も、レポート状態のデバイスにはオフライン状態を送信する必要があります。
例 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