Google Home Developer Center への移行が完了しました。

このページは Cloud Translation API によって翻訳されました。

エラーと例外

このドキュメントでは、スマートホームデバイスで公式にサポートされているエラーと例外の一覧を示します。Google アシスタントがエンドユーザーに特定のコマンドやデバイスの状態に関連する問題を警告できるように、インテントレスポンスまたは（実装している場合は）通知で、これらのエラーコードと例外コードを使用してください。レスポンスに正しくない形式や errorCode が含まれている場合、Google アシスタントは「申し訳ありませんが、<デバイス名> は現在利用できません」などの一般的なエラーメッセージをユーザーに返します。

エラー

問題が原因で実行リクエストまたはクエリリクエストが失敗した場合は、エラーコードを返す必要があります。たとえば、ドアロックが詰まってロックまたはロック解除できない場合は、この状態に関するエラーをユーザーに返す必要があります。

エラーコードは、デバイスレベルまたはグローバルレベルで付加できます。たとえば、ユーザーが 1 つのプロバイダの照明を多数所有しており、それらがハブで制御されている場合、ユーザーがすべての照明をオフにするようリクエストすると、1 つの照明がオフラインの場合はデバイスレベルのエラーが、ハブ全体がオフラインで照明を制御できない場合はグローバルレベルのエラーが返されることがあります。すべてのデバイスがオフラインの場合、グローバルレベルのエラーとデバイスレベルのエラーの使用に違いはありません。

まとめると、次のとおりです。

グローバルレベルのエラー: レスポンス内のすべてのデバイスに同じエラーがある
ローカルレベルのエラー: エラーと成功のケースが混在したレスポンス

グローバルレベルのエラー

次の 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 : <デバイス> のタイマーは <期間> までしか設定できません
actionNotAvailable : 現在、その操作は行えません。
actionUnavailableWhileRunning : <デバイス> は現在実行中のため、変更できません。
alreadyArmed : <デバイス> はすでに監視中です。
alreadyAtMax : <デバイス> はすでに最高温度に設定されています。
alreadyAtMin : <デバイス> はすでに最低温度に設定されています。
alreadyClosed : <デバイス> はすでに閉じられています。
alreadyDisarmed : <デバイス> はすでに解除されています。
alreadyDocked : <デバイス> はすでにドッキングされています。
alreadyInState : <デバイス> はすでにその状態です。
alreadyLocked : <デバイス> はすでにロックされています。
alreadyOff : <デバイス> はすでにオフになっています。
alreadyOn : <デバイス> はすでにオンになっています。
alreadyOpen : <デバイス> はすでに開いています。
alreadyPaused : <デバイス> はすでに一時停止されています。
alreadyStarted : <device(s)> <is/are> already started.
alreadyStopped : <デバイス> はすでに停止しています。
alreadyUnlocked : <デバイス> はすでにロック解除されています。
ambiguousZoneName : 申し訳ありませんが、<デバイス> をかける場所がわかりません。固有の名前をその場所に設定していることを確認してから、もう一度試してください。
amountAboveLimit : <デバイス> でサポートできる上限を超えています。
appLaunchFailed : 申し訳ございませんが、<デバイス> で <アプリ名> を起動できませんでした。
armFailure : <デバイス> を監視できませんでした。
armLevelNeeded : <デバイス> をどのレベルに設定するかがわかりません。「<デバイス> を <低セキュリティ> に設定して」または「<デバイス> を <高セキュリティ> に設定して」と言ってみてください。
authFailure : <デバイス> にアクセスできません。アプリで <デバイス> の設定が完了していることを確認してください。
bagFull : <デバイス> のゴミが一杯です。空にしてからもう一度お試しください。
belowMinimumLightEffectsDuration : 最短設定時間は 5 分です。もう一度お試しください。
belowMinimumTimerDuration : <device(s)> の設定時間が短すぎます。もう一度お試しください。
binFull : <デバイス> <は/は> <満杯のビン/満杯のビン> を持っています。
cancelArmingRestricted : 申し訳ありませんが、<デバイス> の設定を解除できませんでした。
cancelTooLate : キャンセルが間に合いませんでした。代わりに <デバイス> またはアプリを使用してください。
channelSwitchFailed : <channel name> に切り替えられませんでした。後ほど試してください。
chargerIssue : すみません、<device(s)> に <a charger issue/charger issues> が発生しているようです。
commandInsertFailed : <デバイス> のコマンドを処理できません。
deadBattery : <デバイス> のバッテリーが切れています。
degreesOutOfRange : リクエストされた数値は <デバイス> の設定範囲外です。
deviceAlertNeedsAssistance : <device(s)> <has/have> an active alert and <need(s)> your assistance.（<デバイス> にアクティブなアラートがあり、サポートが必要です。）
deviceAtExtremeTemperature : <デバイス> が <極端な温度> になっています。
deviceBusy : 申し訳ございません。<デバイス> は現在作動中です。
deviceCharging : すみません、<device(s)> は充電中のため、その操作を行えません。
deviceClogged : <デバイス> が詰まっています。
deviceCurrentlyDispensing : <デバイス> は現在給餌中です。
deviceDoorOpen : <デバイス> のドアが開いています。閉じてからもう一度お試しください。
deviceHandleClosed : <デバイス> のハンドルが閉じられています。開いてからもう一度お試しください。
deviceJammingDetected : <device(s)> <is/are> jammed.
deviceLidOpen : <デバイス> の蓋が開いています。蓋を閉じてからもう一度お試しください。
deviceNeedsRepair : <デバイス> の修理が必要です。お近くの販売業者にお問い合わせください。
deviceNotDocked : 申し訳ございません。<デバイス> がドッキングされていないようです。<それ/それら> をドッキングしてから、もう一度お試しください。
deviceNotFound : <device(s)> <is/are>n't available. もう一度セットアップしてみてください。
deviceNotMounted : すみません、<デバイス> は取り付けられていないため、その操作を行えません。
deviceNotReady : <デバイス> の準備ができていません。
deviceStuck : <デバイス> が動かなくなっており、サポートが必要です。
deviceTampered : <device(s)> <has/have> been tampered with.
deviceThermalShutdown : 周辺温度が高すぎるか低すぎるため、<デバイス> は停止しました。
directResponseOnlyUnreachable : <デバイス> はリモートコントロールに対応していません。
disarmFailure : <device(s)> の武装を解除できませんでした。
discreteOnlyOpenClose : 申し訳ありませんが、<デバイス> は完全に開閉することしかできません。
dispenseAmountAboveLimit : <device(s)> の給餌量が多すぎます。
dispenseAmountBelowLimit : <device(s)> の給餌量が少なすぎます。
dispenseAmountRemainingExceeded : <デバイス> には、<ディスペンスアイテム> が不足しています。
dispenseFractionalAmountNotSupported : <デバイス> は <ディスペンスアイテム> の一部をディスペンスできません。
dispenseFractionalUnitNotSupported : <device(s)> doesn't support fractions of that unit for <dispense item>.
dispenseUnitNotSupported : <デバイス> は <ディスペンスアイテム> の単位をサポートしていません。
doorClosedTooLong : <デバイス> のドアが前回使用時から開けられていません。ドアを開けて中にものが入っていることを確認してから、もう一度試してください。
emergencyHeatOn : <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
floorUnreachable : <デバイス> がその部屋まで移動できません。<デバイス> を正しい階に移動してから、もう一度お試しください。
functionNotSupported : 実際には、<デバイス> はその機能に対応していません。
genericDispenseNotSupported : 取り出すアイテムの名前を指定してもう一度試してください。
hardError : エラーが発生したためスマートホームデバイスを操作できません。
hardError : エラーが発生したためスマートホームデバイスを操作できません。
inAutoMode : <device(s)> <is/are> 現在自動モードに設定されています。温度を変更するには、別のモードに切り替えてください。
inAwayMode : <デバイス> は現在、外出モードに設定されています。サーモスタットを操作するには、スマートフォン、タブレット、またはパソコンの Nest アプリを使用して、手動で在宅モードに切り替えてください。
inDryMode : <デバイス> は現在ドライモードに設定されています。温度を変更するには、別のモードに切り替えてください。
inEcoMode : <デバイス> は現在エコモードに設定されています。温度を変更するには、別のモードに切り替えてください。
inFanOnlyMode : <device(s)> <is/are> 現在送風のみモードに設定されています。温度を変更するには、別のモードに切り替えてください。
inHeatOrCool : <device(s)> <is/are>n't in heat/cool mode.
inHumidifierMode : <device(s)> <is/are> currently set to humidifier mode. 温度を変更するには、別のモードに切り替えてください。
inOffMode : <device(s)> <is/are> currently off. To change the temperature, you'll need to switch <it/them> to a different mode.
inPurifierMode : <device(s)> <is/are> 現在空気清浄モードに設定されています。温度を変更するには、別のモードに切り替えてください。
inSleepMode : <デバイス> がスリープモードになっている。しばらくしてからもう一度お試しください。
inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
lockFailure : <デバイス> をロックできませんでした。
lockedState : <デバイス> は現在ロックされています。
lockedToRange : その温度は <デバイス> の固定範囲外です。
lowBattery : <デバイス> のバッテリー残量が少なくなっています。
maxSettingReached : <device(s)> <is/are> already set to the highest setting.
maxSpeedReached : <デバイス> はすでに最大速度に設定されています。
minSettingReached : <デバイス> はすでに最小設定になっています。
minSpeedReached : <デバイス> はすでに最小速度に設定されています。
monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connection to the monitoring service.
needsAttachment : <device(s)> に必要なアタッチメントがありません。取り付けてから、もう一度試してください。
needsBin : <デバイス> にダストボックスがないようです。取り付けてから、もう一度試してください。
needsPads : <デバイス> には新しいパッドが必要です。
needsSoftwareUpdate : <device(s)> <need(s)> a software update.
needsWater : <デバイス> に水が必要です。
networkProfileNotRecognized : 申し訳ありませんが、<デバイス> の "<ネットワークプロファイル>" を認識できません。
networkSpeedTestInProgress : <network> の <speed/speeds> をテスト中です。
noAvailableApp : 申し訳ございませんが、<アプリ名> はご利用いただけません。
noAvailableChannel : すみません、<チャンネル名> は利用できません。
noChannelSubscription : 申し訳ございませんが、現在 <チャンネル名> チャンネルに登録されていません。
noTimerExists : <デバイス> に設定されているタイマーはありません。
notSupported : 申し訳ございませんが、このモードは <デバイス> ではご利用いただけません。
obstructionDetected : <デバイス> が障害物を検出しました。
offline , deviceOffline : 申し訳ございません。現在、<デバイス> はご利用いただけません。
onRequiresMode : オンにするモードを指定してください。
passphraseIncorrect : PIN が正しくありません。
percentOutOfRange : 申し訳ありませんが、<デバイス> を <パーセント> に設定できません。
pinIncorrect : (passphraseIncorrect)
rainDetected : 雨が検知されたため、<デバイス> を開けませんでした。
rangeTooClose : 指定した温度は、<デバイス> の暖房・冷房モードの範囲に近すぎます。もっと差がある温度を指定してください。
relinkRequired : お使いのアカウントでエラーが発生しました。Google Home アプリまたはアシスタントアプリで <デバイス> をリンクし直してください。
remoteSetDisabled :
- 省略可能なパラメータ errorCodeReason
- currentlyArmed - すでにセキュリティシステムにより監視中です。変更は <デバイス> またはアプリから行ってください。
- remoteUnlockNotAllowed - 申し訳ございませんが、<デバイス> のリモートロック解除はできません。
- remoteControlOff - その操作は無効になっています。<デバイス> のリモートコントロールを有効にしてから、もう一度試してください。
- childSafetyModeActive - チャイルドセーフティモードが有効になっている場合、<デバイス> に対するその操作は無効になります。
roomsOnDifferentFloors : <デバイス> は別の階にあるため、これらの部屋に入ることができません。
safetyShutOff : <デバイス> は安全遮断モードになっているため、手動で調整してください。
sceneCannotBeApplied : 申し訳ありませんが、<デバイス> を適用できません。
securityRestriction : <デバイス> にセキュリティ制限があります。
softwareUpdateNotAvailable : 申し訳ございませんが、<device(s)> で利用可能なソフトウェアアップデートはありません。
startRequiresTime : その操作を行うには、<デバイス> の作動時間を指定してください。
stillCoolingDown : <デバイス> はまだ冷却中です。
stillWarmingUp : <デバイス> はまだ準備中です。
streamUnavailable : <デバイス> からのストリームは現在利用できません。
streamUnplayable : 申し訳ありませんが、現時点では <デバイス> からのストリームを再生できません。
tankEmpty : <デバイス> の <タンク> が空になっています。<タンク> に補充してから、もう一度お試しください。
targetAlreadyReached : すでにその温度に設定されています。
timerValueOutOfRange : <device(s)> をその時間に設定することはできません。
tooManyFailedAttempts : 失敗回数が多すぎます。デバイスのアプリでアクションを完了してください。
transientError : <デバイス> の操作でエラーが発生しました。もう一度お試しください。
turnedOff , deviceTurnedOff : <デバイス> は現在オフになっています。
unableToLocateDevice : <デバイス> を見つけることができませんでした。
unknownFoodPreset : <デバイス> は、そのプリセットメニューに対応していません。
unlockFailure : <デバイス> をロック解除できませんでした。
unpausableState : <デバイス> は現在一時停止できません。
userCancelled : ok
valueOutOfRange : <device(s)> をその温度に設定することはできません。

オンラインとオフラインの状態のレポート

デバイスがオフラインの場合は、デバイスの動作から 5 分以内に Report State に <code{"online": code="" dir="ltr" false}<="" translate="no"> を通知する必要があります。逆に、デバイスがオンライン状態に戻った場合は、デバイスの動作から 5 分以内に Report State に <code{"online": code="" dir="ltr" translate="no" true}<=""> を通知する必要があります。デバイスがオンラインに戻るたびに、パートナーは reportStateAndNotification API を使用して、現在のデバイスの状態をすべて報告する必要があります。この例は、light デバイスタイプがオンラインであり、現在のすべてのデバイスの状態をレポートしていることを示しています。

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

例外

コマンドに関連付けられた問題やアラートがある場合は、例外を返す必要があります。コマンドは成功することも失敗することもあります。

コマンドが成功した場合（ステータス = 「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 : <デバイス> のゴミが一杯です。空にしてからもう一度お試しください。
binFull : <デバイス> <は/は> <満杯のビン/満杯のビン> を持っています。
carbonMonoxideDetected : <家名> で一酸化炭素が検出されました。
deviceAtExtremeTemperature : <デバイス> が <極端な温度> になっています。
deviceJammingDetected : <device(s)> <is/are> jammed.
deviceMoved : <device(s)> <was/were> moved.
deviceOpen : <デバイス> が開いています。
deviceTampered : <device(s)> <has/have> been tampered with.
deviceUnplugged : <デバイス> が取り外されました。
floorUnreachable : <デバイス> がその部屋まで移動できません。<デバイス> を正しい階に移動してから、もう一度お試しください。
hardwareFailure : <device(s)> <has/have> a hardware problem.
inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
isBypassed : <device(s)> <is/are> currently bypassed.
lowBattery : <デバイス> のバッテリー残量が少なくなっています。
motionDetected : <デバイス> が <検出> モーションを検出しました。
needsPads : <デバイス> には新しいパッドが必要です。
needsSoftwareUpdate : <device(s)> <need(s)> a software update.
needsWater : <デバイス> に水が必要です。
networkJammingDetected : ホームネットワークと <デバイス> が接続されていません。
noIssuesReported : <デバイス> で問題は報告されていません。
roomsOnDifferentFloors : <デバイス> は別の階にあるため、これらの部屋に入ることができません。
runCycleFinished : <デバイス> は実行を終了しました。
securityRestriction : <デバイス> にセキュリティ制限があります。
smokeDetected : <家名> で煙が検出されました。
tankEmpty : <デバイス> の <タンク> が空になっています。<タンク> に補充してから、もう一度お試しください。
usingCellularBackup : <device(s)> <is/are> using cellular backup.
waterLeakDetected : <device(s)> <detect(s)> a water leak.

</code{"online":></code{"online":>