エラーと例外

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

エラー

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

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

デバイスがオフラインの場合、デバイスの動作から 5 分以内に Report State に {"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 が生成されます。

例外

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

コマンドが成功した場合（ステータス =「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 が生成されます。