action.devices.EXECUTE

このインテントは、スマートホーム デバイスで実行するコマンドを送信します。

フルフィルメントは、各コマンドを処理して対応するデバイスに送信し、EXECUTE レスポンスで新しい状態を返す必要があります。

1 つの EXECUTE インテントで、複数のコマンドで複数のデバイスをターゲットにできます。たとえば、トリガーされたインテントでは、一連のライトに明るさと色の両方を設定したり、複数のライトをそれぞれ別の色に設定したりできます。

詳細については、クエリと実行をご覧ください。

リクエストの形式

フィールド タイプ 説明
requestId 文字列

必須。

リクエストの ID。

inputs 配列

必須。

インテント リクエストと一致する入力のリスト。

[item, ...] オブジェクト

インテント リクエストに関連付けられているタイプとペイロード。

intent

必須。

(定数値: "action.devices.EXECUTE"

インテント リクエストのタイプ。

payload オブジェクト

必須。

EXECUTE リクエスト ペイロード。

commands 配列

必須。

デバイスのターゲットとコマンドのペアのリスト。

[item, ...] オブジェクト

接続されたデバイス ターゲットで実行するコマンドのセット。

devices 配列

必須。

対象デバイスのリスト。

[item, ...] オブジェクト

実行するデバイス ターゲット。

id 文字列

必須。

SYNC で指定された ID でのデバイス ID。

customData オブジェクト

不透明な customData オブジェクトが SYNC で指定されている場合は、ここで送信されます。

execution 配列

必須。

対象デバイスで実行するコマンドのリスト。

[item, ...] オブジェクト

デバイスのコマンド

command 文字列

必須。

実行するコマンド。通常、パラメータを伴います。

params オブジェクト

各コマンドのパラメータに対応する。

インテント実行リクエスト

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123",
                "customData": {
                  "fooValue": 74,
                  "barValue": true,
                  "bazValue": "sheepdip"
                }
              },
              {
                "id": "456",
                "customData": {
                  "fooValue": 36,
                  "barValue": false,
                  "bazValue": "moarsheep"
                }
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.OnOff",
                "params": {
                  "on": true
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

レスポンスの形式

フィールド タイプ 説明
requestId 文字列

必須。

対応するリクエストの ID。

payload オブジェクト

必須。

インテント レスポンスのペイロード。

errorCode 文字列

認証エラーやデベロッパー システムが利用できないトランザクション全体のエラーコード。個々のデバイスエラーについては、デバイス オブジェクト内で errorCode を使用します。

debugString 文字列

エラーの詳細。ユーザーには表示されませんが、開発中にログに記録または使用される可能性があります。

commands 配列

各オブジェクトには、1 つ以上のデバイスとレスポンスの詳細が含まれます。注意: リクエストと同じ形ではグループ化されない可能性があります。たとえば、リクエストに対して 7 個のライトがオンになり、3 個のライトが成功し、4 個が失敗し、レスポンスに 2 個のグループが含まれることになります。

[item, ...] オブジェクト

デバイスの実行結果。

ids 配列

必須。

このステータスに対応するデバイス ID のリスト。

[item, ...] 文字列

デバイス ID。

status 文字列

必須。

実行オペレーションの結果。

サポートされている値:

SUCCESS
コマンドが成功したことを確認します。
PENDING
コマンドはキューに追加されますが、成功が想定されています。
OFFLINE
対象デバイスがオフライン状態であるか、到達不能です。
EXCEPTIONS
コマンドに関連する問題またはアラートがあります。コマンドが成功または失敗する可能性があります。通常、このステータス タイプは、接続されている別のデバイスに関する追加情報を送信する場合に使用します。
ERROR
対象デバイスでコマンドを実行できません。
states オブジェクト

各トレイトのスキーマ リファレンスに記載されているトレイトごとの状態を満たしていること。実行後の状態(利用可能な場合)です。

online ブール値

デバイスがオンライン(つまりアクセス可能)かどうかを示します。

errorCode 文字列

ERROR 状態を、必要に応じて、プリセットのエラーコードから拡張します。ユーザーに表示されるエラーに対応付けられます。

EXECUTE インテント レスポンス

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      },
      {
        "ids": [
          "456"
        ],
        "status": "ERROR",
        "errorCode": "deviceTurnedOff"
      }
    ]
  }
}