エラーと例外

このドキュメントでは、Smart API に関して公式にサポートされるエラーと例外について説明します。 できます。以下のエラーコードと例外コードをインテントで使用してください 通知内のいずれかで Google アシスタントがエンドユーザーにアラートを通知します。 デバイスの状態を指定します。回答の形式が正しくない場合や、 errorCode の場合、Google アシスタントから次のような一般的なエラー メッセージが表示されます。 「申し訳ありませんが、デバイスは現在ご利用いただけません。」

エラー

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

エラーコードは、デバイスレベルまたはグローバル レベルで付加できます。たとえば ユーザーが 1 つのプロバイダが提供する多数のライトをハブで制御している場合、 ユーザーがすべてのライトを消すよう要求した場合、プロバイダは 1 つのライトがオフラインの場合はデバイスレベルのエラー、グローバル レベルのエラーの場合は ハブ全体がオフラインになっていて、ライトを操作できない。すべての デバイスがオフラインの場合、グローバル レベルとデバイスレベルのどちらを使用するかに違いはありません。 表示されます。デバイスがオフラインの場合、{"online": false} の状態を reportState を返しても、 deviceOffline エラーコード。

概要は次のとおりです。

• グローバル レベルのエラー: レスポンス内のすべてのデバイスで同じエラーが返される
• ローカルレベルのエラー: エラーと成功ケースが混在するレスポンス

で確認できます。

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

次の 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 を返します。

たとえば、乾燥機の lint の画面がいっぱいになっていても、 この状態について警告することをおすすめします。同様に デバイスのバッテリー残量が少なくなっていても、コマンドを実行できます。 デバイスの電池残量が少なくなっていることを知らせます。

例外によりコマンドが失敗した場合、ステータスは「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 が生成されます。