このドキュメントでは、スマートホーム デバイスで公式にサポートされているエラーと例外について説明します。以下のエラーコードと例外コードをインテント レスポンス内、または実装済みの場合は通知で使用してください。これにより、Google アシスタントが特定のコマンドやデバイスの状態に関連する問題をエンドユーザーに警告できるようになります。レスポンスに誤った形式や errorCode
が含まれている場合、Google アシスタントは「申し訳ありませんが、デバイスは現在ご利用いただけません」などの一般的なエラー メッセージを表示します。
エラー
問題によって実行リクエストまたはクエリ リクエストが失敗した場合は、エラーコードを返す必要があります。たとえば、ドアロックが故障してロックまたはロック解除できない場合は、この状態に関するエラーをユーザーに返す必要があります。
エラーコードは、デバイスレベルまたはグローバル レベルで付加できます。たとえば、ユーザーが 1 つのプロバイダから多数のライトを所有していて、それらがハブによって制御されている場合、ユーザーがすべてのライトの消灯をリクエストすると、プロバイダは、1 つのライトがオフラインの場合はデバイスレベルのエラーを返し、ハブ全体がオフラインになってライトを制御できない場合はグローバル レベルのエラーを返す可能性があります。すべてのデバイスがオフラインの場合、グローバル レベルのエラーとデバイスレベルのエラーの使用に違いはありません。デバイスがオフラインの場合は、deviceOffline
エラーコードを返す場合でも、reportState で {"online": false}
の状態を報告する必要があります。
概要は次のとおりです。
- グローバル レベルのエラー: レスポンス内のすべてのデバイスで同じエラーが返される
- ローカルレベルのエラー: エラーと成功ケースが混在するレスポンス
グローバル レベルのエラー
次の JSON スニペットは、QUERY または EXECUTE レスポンスでグローバル レベルのエラーを返す方法を示しています。
ハブがオフラインであることによるグローバル レベルのエラー deviceOffline
の例:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "deviceOffline", "status" : "ERROR" } }
ハブによるグローバル レベルのエラー inSoftwareUpdate
の例:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "inSoftwareUpdate", "status" : "ERROR" } }
デバイスレベルのエラー
QUERY レスポンス
次の JSON スニペットは、QUERY レスポンスでデバイスレベルのエラーを返す方法を示しています。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "errorCode": "deviceOffline", "status" : "ERROR" }, "device-id-2": { "errorCode": "deviceOffline", "status" : "ERROR" } } } }
EXECUTE レスポンス
次の JSON スニペットは、EXECUTE レスポンスでデバイスレベルのエラーを返す方法を示しています。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "device-id-2" ], "status": "SUCCESS", "states": { "on": true, "online": true } } ] } }
エラーのある通知
プロアクティブ通知
次の JSON スニペットは、プロアクティブな通知でデバイスレベルのエラーを報告する方法を示しています。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } } } } }
フォローアップの回答
次の JSON スニペットは、フォローアップ レスポンスでデバイスレベルのエラーを報告する方法を示しています。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "PLACEHOLDER" } } } } } } }
エラーリスト
次のエラーでは、関連する TTS がデバイスに生成されます。
- aboveMaximumLightEffectsDuration : これは最大継続時間の 1 時間を超えています。もう一度お試しください。
- aboveMaximumTimerDuration : <device(s)> は <time period> までしか設定できません
- actionNotAvailable : 現在、その操作を行えないようです。
- actionUnavailableWhileRunning : <デバイス> は動作中のため、変更できません。
- alreadyArmed : <デバイス> は監視済みです。
- alreadyAtMax : <device(s)> <is/are> は、すでに最高温度に設定されています。
- alreadyAtMin : <device(s)> <is/are> は、すでに最低温度に設定されています。
- alreadyClosed : <デバイス> <is/are> はすでに閉まっています。
- すでに監視解除済み : <デバイス> <は監視中です。
- alreadyDocked : <デバイス> は、すでにホルダーに装着されています。
- alreadyInState : <device(s)> <is/are> はすでにその状態です。
- alreadyLocked : <デバイス> <is/are> はすでにロックされています。
- alreadyOff : <デバイス> <is/are> はすでにオフになっています。
- alreadyOn : <デバイス> <is/are> はすでにオンです。
- alreadyOpen : <デバイス> <is/are> はすでに開いています。
- すでに一時停止中 : <デバイス> <は> は一時停止中です。
- alreadyStarted : <デバイス> <is/are> はすでに開始されています。
- alreadyStopped : <デバイス> <is/are> はすでに停止している。
- alreadyUnlocked : <デバイス> <is/are> はすでにロック解除されています。
- ambiguousZoneName : 申し訳ありませんが、<device(s)> ではどのゾーンのことかわかりません。ゾーンに一意の名前があることを確認してから、もう一度お試しください。
- amountAboveLimit : これは <device(s)> でサポート可能な量を超えています。
- appLaunchFailed : <アプリ名> を <デバイス> で起動できませんでした。
- armFailure : <device(s)> で監視することができませんでした。
- armLevelNeeded : <device(s)> をどのレベルに設定するかわかりません。「<デバイス> を <セキュリティが低い> に設定して」、「<デバイス> を <セキュリティ レベルが高い> に設定して」と言ってみてください
- authFailure : <device(s)> にアクセスできないようです。アプリで <device/devices> <is/are> が完全にセットアップされていることを確認してみてください。
- bagFull : <デバイス> <has/have> <バッグ一杯/バッグ一杯>。<it/them> を空にして、もう一度お試しください。
- belowMinimumLightEffectsDuration : 最小継続時間の 5 分を下回っています。もう一度お試しください。
- belowMinimumTimerDuration : 短時間、<device(s)> を設定できません。もう一度お試しください。
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- cancelArmingRestricted : <device(s)> による監視をキャンセルできませんでした。
- cancelTooLate : すみません、キャンセルできる期間を過ぎています。代わりに <デバイス> またはアプリを使用してください。
- channelSwitchFailed : チャンネル <channel name> への切り替えに失敗しました。しばらくしてからもう一度お試しください。
- chargeIssue : 恐れ入りますが、<device(s)> は <has/have> <a 充電器の問題/charger issues> のようです。
- commandInsertFailed : <device(s)> のコマンドを処理できません。
- deadBattery : <device(s)> <has/have> <a を表示しにくい/deadbattery>.
- degreeOutOfRange : リクエストされた度数は <device(s)> の範囲外です。
- deviceAlertNeedsAssistance : <デバイス> には有効なアラートが <ある/ある> あなたのサポートは <ニーズ> である。
- deviceAtExtremeTemperature : <デバイス> は<極端な温度または極端な温度> にある。
- deviceBusy : <device(s)> はすでになんらかの操作を行っているようです。
- deviceCharging : <device(s)> は、(ha_shared.ItsThatre size=$item.devices.total_device_count) を充電しているため、その操作を行えません。
- deviceClogged : <device(s)> が詰まっているようです。
- deviceCurrentlyDispensing : <device(s)> はすでに何かを分配しています。
- deviceDoorOpen : <デバイス> のドアが開いています。閉じてから、もう一度お試しください。
- deviceHandleClosed : ハンドルは <デバイス> で閉じられています。開いてもう一度お試しください。
- deviceJammingDetected : <デバイス> <は> は動きません。
- deviceLidOpen : <デバイス> のカバーが開いています。閉じてから、もう一度お試しください。
- deviceNeedsRepair : <デバイス> <need(s)> を修理する必要があります。お近くのサービス ディーラーにお問い合わせください。
- deviceNotDocked : ホルダーに装着してからもう一度お試しください。
- deviceNotFound : <デバイス> は利用できません。もう一度セットアップしてみてください。
- deviceNotMounted :
- deviceNotReady : <デバイス> は準備未完了です。
- deviceStuck : <デバイス> は停止しており、サポートが必要です。
- deviceTampered : <デバイス> <has/have> が改ざんされました。
- deviceThermalShutdown : 極端な高温のため、<device(s)> はシャットダウンしたようです。
- directResponseOnlyUnreachable : <デバイス> はリモート コントロールを<サポートしていない/サポートしていません>。
- disarmFailure : <device(s)> で監視を解除できませんでした。
- disreteOnlyOpenClose : 申し訳ありません。<device(s)> は完全に開いたり閉じたりできます。
- dispenseAmountIncreaseLimit : <device(s)> は大量の給与ができません。
- dispenseAmountBelowLimit : <device(s)> では少量の給与ができません。
- dispenseAmountRemainingExceeded : <device(s)> には、それを行うのに十分な <dispense item> がありません。
- dispenseFractionalAmountNotSupported : <device(s)> は <dispense item> を小数で処理できません。
- dispenseFractionalUnitNotSupported : <device(s)> は、<dispense item> に対してその単位の小数をサポートしていません。
- dispenseUnitNotSupported : <device(s)> は <dispense item> に対してその単位をサポートしていません。
- doorClosedTooLong : <device(s)> のドアが開けられてからしばらく時間が経っています。ドアを開けて中に何かが入っていることを確認してから、もう一度お試しください。
- EmergencyHeatOn : <デバイス> は緊急ヒーターモードになっているため、<it/they> は手で調整する必要があります。
- faultyBattery : <デバイス> <持っている/持っている> <バッテリーの不良/バッテリーの不良>。
- FloorUnreachable : <device(s)> はその部屋にアクセスできません。<it/them> を正しい階に移動してから、もう一度お試しください。
- functionNotSupported : 実際には、<device(s)> はこの機能を<サポートしていない/サポートしていません>。
- genericDispenseNotSupported : 分配したいものを把握する必要があります。アイテムの名前でもう一度お試しください。
- hardError : エラーが発生したため、スマートホーム デバイスを操作できません。
- hardError : エラーが発生したため、スマートホーム デバイスを操作できません。
- inAutoMode : <デバイス> は自動モードになっています。温度を変更するには、別のモードに切り替える必要があります。
- inAwayMode : <デバイス> <は> は現在外出モードに設定されています。サーモスタットを操作するには、スマートフォン、タブレット、またはパソコンの Nest アプリを使用して手動で在宅モードに切り替える必要があります。
- inDryMode : <デバイス> は現在、除湿モードになっています。温度を変更するには、別のモードに切り替える必要があります。
- inEcoMode : <デバイス> はエコモードになっています。温度を変更するには、別のモードに切り替える必要があります。
- inFanOnlyMode : <device(s)> <is/are> は現在、送風モードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
- inHeatOrCool : <device(s)> <は暖房・冷房モードではありません。
- inHumidifierMode : <デバイス> <is/are> は現在加湿モードになっています。温度を変更するには、別のモードに切り替える必要があります。
- inOffMode : <デバイス> は現在オフになっています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
- inPurifierMode : <device(s)> <is/are>は現在、空気清浄モードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
- inSleepMode : <デバイス> はおやすみモードになっています。しばらくしてからもう一度お試しください
- inSoftwareUpdate : <デバイス> はソフトウェア アップデート中です。
- lockFailure : <device(s)> をロックできませんでした。
- lockState : <device(s)> <is/are>現在ロックされています。
- lockToRange : その温度は <device(s)> のロック範囲外です。
- lowBattery : <デバイス> はバッテリー残量が少なくなっています。
- maxSettingReached : <device(s)> <is/are> はすでに最も高い設定に設定されています。
- maxSpeedReached : <デバイス> <is/are> はすでに最高速度に設定されています。
- minSettingReached : <デバイス> <is/are> はすでに最も低い設定に設定されています。
- minSpeedReached : <デバイス> <は> はすでに最小速度に設定されています。
- monitoringServiceConnectionLost : <device(s)> <has/have> は Monitoring サービスに対する <its/that> の接続を失いました。
- needAttachment : <デバイス> <is/are> に必要な添付ファイルがないようです。交換して、もう一度お試しください。
- needBin : <device(s)> にゴミ箱がありません。交換して、もう一度お試しください。
- needPads : <デバイス> <need(s)> 新しいパッド。
- needSoftwareUpdate : <デバイス> <ソフトウェア アップデートが必要。
- needWater : <デバイス> <need(s)> 水。
- networkProfileNotRecognized : 「<device(s)> で「<ネットワーク プロファイル>」を認識できません。
- networkSpeedTestInProgress : すでに <network> <speed/speeds>> をテストしています。
- noAvailableApp : <アプリ名> は利用できないようです。
- noAvailableChannel : チャンネル <チャンネル名> は視聴できません。
- noChannelSubscription : 現在、お客様はチャンネル <channel name> に登録していません。
- noTimerExists : <device(s)> に設定されているタイマーはありません。
- notSupported : そのモードは <device(s)> では利用できません。
- obstructionDetected : <デバイス> が障害物を検出しました。
- オフライン , deviceOffline : 現在 <device(s)> は<is/are>利用できないようです。
- onRequiresMode : オンにするモードを指定してください。
- passphraseIncorrect : PIN が正しくないようです。
- percentOutOfRange : <device(s)> を <percent> に設定することはできません。
- pinIncorrect : (passphraseIncorrect)
- rainDetected : 雨が検知されたため <デバイス> を開けませんでした。
- rangeTooClose : <device(s)> の暖房 / 冷房範囲には近すぎます。もっと離れた温度を選択してください。
- relinkRequired : アカウントでエラーが発生したようです。Google Home アプリまたはアシスタント アプリを使用して <device(s)> を再リンクしてください。
-
remoteSetDisabled
:
- 省略可能なパラメータ
errorCodeReason
currentlyArmed
- すでにセキュリティで監視中のため、<device(s)> かアプリを使用して変更してください。remoteUnlockNotAllowed
- <デバイス> をリモートでロック解除できません。remoteControlOff
- この操作は現在無効になっています。<device(s)> でリモコンを有効にしてから、もう一度お試しください。childSafetyModeActive
- 子ども用セーフティ モードが有効になっている場合、<device(s)> ではこの操作は無効になります。
- 省略可能なパラメータ
- RoomOnDifferentFloors : <device(s)> は異なる階にあるため、これらの部屋に到達できません。
- safetyShutOff : <device(s)> は安全遮断モードになっているので、<it/they> は手で調整する必要があります。
- sceneCannotBeApplied : <device(s)> は適用できません。
- securityRestriction : <デバイス> はセキュリティ制限を<持っている/持っています>。
- SoftwareUpdateNotAvailable : <device(s)> で利用できるソフトウェア アップデートはありません。
- startRequiresTime : その操作を行うには、<device(s)> の実行時間を指定してください。
- illCoolingDown : <デバイス> はまだクールダウン中です。
- illWarmingUp : <デバイス> は<ph type="x-smartling-void-element"><wbr /></ph>まだ<ph type="x-smartling-void-element"><wbr /></ph>ウォームアップ<ph type="x-smartling-void-element"><wbr /></ph>です。
- streamUnavailable : 現在 <device(s)> からストリーミングを視聴できません。
- streamUnplayable : 現在、<device(s)>からストリームを再生できません。
- tankEmpty : <デバイス> <has/have> <空のタンク/空のタンク>。<it/them> に入力し、もう一度お試しください。
- targetAlreadyReached : その期間はすでに現在の気温のようです。
- timeValueOutOfRange : その時間には <device(s)> を設定できません。
- tooManyFailedAttempts : 失敗回数が上限を超えました。この操作を完了するには、デバイスのアプリに移動してください。
- transientError : <device(s)> の操作中にエラーが発生しました。もう一度お試しください。
- off 、 deviceTurnedOff : <device(s)> は <is/are> 現在オフになっています。
- UnableToLocationsDevice : <device(s)> を見つけることができませんでした。
- unknownFoodPreset : <device(s)> はそのフード プリセットをサポートしていません。
- unlockFailure : <device(s)> をロック解除できませんでした。
- unpausableState : 現在、<device(s)> は一時停止できません。
- userCancelled : OK
- valueOutOfRange : <device(s)> をその温度に設定することはできません。
例外
コマンドに関連する問題またはアラートがある場合は、例外を返す必要があります。コマンドは成功することも失敗することもあります。
コマンドが成功した場合は(ステータス = "SUCCESS")、StatusReport
トレイトを使用する(ターゲット以外のデバイスの場合)、または適切な exceptionCode
を返す(ターゲット デバイスの場合)ことによって、例外を報告します。
たとえば、乾燥機のリント画面がいっぱいになっていても、ユーザーは乾燥機を起動できますが、この状態について警告することをおすすめします。同様に、デバイスのバッテリー残量が少なくなっていない場合でもコマンドを実行できますが、デバイスのバッテリー残量が少なくなっていることをユーザーに知らせます。
例外によりコマンドが失敗した場合、ステータスは「EXCEPTIONS」になり、例外は StatusReport
トレイトを使用して報告する必要があります。
ターゲット デバイスに関する非ブロック例外(SUCCESS)
次の例は、ドアをロックする場合です。
玄関ドアのロックのバッテリー残量が少なくなっています。玄関のドアをロックします。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
StatusReport を使用した別のデバイスに関する非ブロック例外(SUCCESS)
この例は、セキュリティ システムを作動します。わかりました。セキュリティ システムを作動します。正面の窓が開いています。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [{ "blocking": false, "deviceTarget": "sensor_id1", "priority": 0, "statusCode": "deviceOpen" }] } }] } }
StatusReport を使用して別のデバイスに関する例外をブロックする
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "on": true, "online": true, "status": "EXCEPTIONS", "currentStatusReport": [{ "blocking": true, "deviceTarget": "device-id-1", "priority": 0, "statusCode": "lowBattery" }, { "blocking": true, "deviceTarget": "front_window_id", "priority": 1, "statusCode": "deviceOpen" }, { "blocking": true, "deviceTarget": "back_window_id", "priority": 1, "statusCode": "deviceOpen" } ] } } } }
例外リスト
次の例外が発生すると、デバイス上で関連する TTS が生成されます。
- bagFull : <デバイス> <has/have> <バッグ一杯/バッグ一杯>。<it/them> を空にして、もう一度お試しください。
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- carbonMonoxideDetected : <家の名前> で一酸化炭素が検知されました。
- deviceAtExtremeTemperature : <デバイス> は<極端な温度または極端な温度> にある。
- deviceJammingDetected : <デバイス> <は> は動きません。
- deviceMoved : <デバイス> は移動されました/移動されました。
- deviceOpen : <デバイス> <は> 開いています。
- deviceTampered : <デバイス> <has/have> が改ざんされました。
- deviceUnplugged : <デバイス> <is/are> が電源に接続されていません。
- FloorUnreachable : <device(s)> はその部屋にアクセスできません。<it/them> を正しい階に移動してから、もう一度お試しください。
- HardwareFailure : <デバイス> にはハードウェアの問題があります。
- inSoftwareUpdate : <デバイス> はソフトウェア アップデート中です。
- isBypassed : <デバイス> が現在バイパスされています。
- lowBattery : <デバイス> はバッテリー残量が少なくなっています。
- motionDetected : <デバイス> <detect(s)> モーション。
- needPads : <デバイス> <need(s)> 新しいパッド。
- needSoftwareUpdate : <デバイス> <ソフトウェア アップデートが必要。
- needWater : <デバイス> <need(s)> 水。
- networkJammingDetected : <device(s)> へのホーム ネットワーク接続が正常に動作していません。
- noIssuesReported : <device(s)> は問題を報告していません。
- RoomOnDifferentFloors : <device(s)> は異なる階にあるため、これらの部屋に到達できません。
- runCycleFinished : <device(s)> <has/have> は実行を終了しました。
- securityRestriction : <デバイス> はセキュリティ制限を<持っている/持っています>。
- smokeDetected : <家の名前> で煙が検知されました。
- tankEmpty : <デバイス> <has/have> <空のタンク/空のタンク>。<it/them> に入力し、もう一度お試しください。
- usingCellularBackup : <デバイス> は遠隔バックアップを使用しています。
- waterLeakDetected : <デバイス> <水漏れを検出>。