Alexa.ThermostatControllerインターフェース

Alexa.ThermostatControllerインターフェース

ユーザーがスマートサーモスタットを制御できるように、Alexaスキルに Alexa.ThermostatController インターフェイスを実装しましょう。サーモスタットでは、ヒーター、エアコン、シーリングファン、温水器などのデバイスを制御できます。スマートホームスキルの詳細については、スマートホームスキルを理解するを参照してください。

サーモスタットは、温度を感知し、計測温度を所定の設定値や指定された温度範囲内に保持しようとするデバイスです。ThermostatControllerインターフェースは、最大2つの設定値と各種サーモスタットモードを備えた、サーモスタットスケジュールのプログラムが可能なデバイスに使用できます。通常、ThermostatControllerインターフェースは、Alexa.TemperatureSensorインターフェースと合わせて使用します。

デバイスがサポートする機能に基づいて、それ以外のAlexa.ThermostatControllerインターフェースを実装します。

ThermostatControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。

発話

Alexa.ThermostatControllerインターフェースを使用する場合、Alexaサービスが開発者に代わって音声対話モデルを提供します。以下に、ユーザーの発話の例を示します。

アレクサ、サーモスタットを20に設定して
アレクサ、エアコンを24度に設定して
アレクサ、温度を上げて
アレクサ、温度を下げて
アレクサ、サーモスタットを自動に設定して
アレクサ、リビングのエアコンを自動モードにして

Alexa, set thermostat to twenty.
Alexa, set the AC to seventy-five.
Alexa, set the AC to twenty-five degrees for four hours.
Alexa, make it warmer in here.
Alexa, make it cooler in here.
Alexa, set thermostat to automatic.
Alexa, turn off the heat.
Alexa, resume thermostat schedule.
Alexa, what mode is my thermostat set to?

ユーザーがこのような発話をすると、Alexaがそれに対応するディレクティブまたは状態レポートリクエストをスキルに送信します。

サーモスタットの設定値の種類

Alexaは、1つまたは2つの温度値を設定できるサーモスタットをサポートします。

設定値が1つのサーモスタット
設定値が1つのサーモスタットの場合、サーモスタットが保持しようとする温度設定は1つです。たとえば、設定値が1つのサーモスタットは、温度が設定値よりも低くなると暖房をオンにし、温度が設定値よりも高くなると暖房をオフにします。
設定値が2つのサーモスタット
設定値が2つのサーモスタットには、上限と下限の設定値があります。サーモスタットは、この設定値の範囲内に温度を保持します。

サーモスタットは、モードに応じて異なる設定値に対応できます。詳細については、プロパティを参照してください。

サーモスタットのスケジューリング

デバイスが週単位で温度やサーモスタットモードを設定するユーザーリクエストをサポートする場合、Alexa.ThermostatController.Scheduleインターフェースを実装します。

状況に応じた復旧

状況に応じた復旧をサポートするサーモスタットは、設定された温度に予定通りに到達できるよう、時間の余裕を持ってHVACシステムを開始します。スキルがAlexa.ThermostatController.Scheduleを実装し、デバイスが状況に応じた復旧をサポートする場合、予熱または予冷が進行中であることをレポートします。温度がターゲットの設定値に到達したら、状況に応じた復旧が非アクティブであることをレポートします。たとえば、ターゲットの暖房温度が午後6時に21度だった場合、サーモスタットは午後5:55に予熱を開始します。状態の変化をレポートした後、Alexaアプリに予熱または予冷が進行中であることを示す視覚的なキューを表示します。

ユーザーは、Alexa.ThermostatController.Scheduleインターフェースで状況に応じた復旧を有効/無効にできます。

プロパティ

以下の表は、Alexa.ThermostatControllerインターフェースが定義するプロパティを示しています。検出応答で、サポートするプロパティを指定します。すべてのプロパティはオプションです。サーモスタットデバイスのコンポーネントに対応するプロパティのみを含めてください。

プロパティ 説明
targetSetpoint サーモスタットは、温度をこの設定値に保持しようとします。このプロパティは、設定値が1つのサーモスタットで使用します。 Temperature
lowerSetpoint サーモスタットは、温度をこの設定値より上に保持しようとします。このプロパティは、設定値が2つのサーモスタットで使用します。 Temperature
upperSetpoint サーモスタットは、温度をこの設定値より下に保持しようとします。このプロパティは、設定値が2つのサーモスタットで使用します。 Temperature
thermostatMode サーモスタットの現在のモードです。 ThermostatMode
adaptiveRecoveryStatus 予熱または予冷の現在のステータスです。
有効な値は、 PREHEATINGPRECOOLINGINACTIVEです。
文字列

サーモスタットは、モードに応じて異なる設定値に対応できます。たとえば、HEATまたはCOOLモードでサポートするのは目標値のみ、AUTOまたはECOモードでサポートするのは下限値と上限値です。

検出

Alexa.ThermostatControllerをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

Alexaからスキルに状態レポートリクエストが送信されたら、レポートするプロパティのretrievabletrueに設定します。変更レポートでAlexaにプロアクティブにレポートするプロパティのproactivelyReportedtrueに設定します。

表示カテゴリーにはTHERMOSTATを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。

configurationオブジェクト

ThermostatControllerには、標準の検出応答フィールドのほかに、次のフィールドを含むconfigurationオブジェクトを含めます。

フィールド 説明 必須
supportedModes デバイスがサポートするモードです。 thermostatMode文字列の配列です。
supportsScheduling 期間を示す設定値をユーザーが指定できる場合はtrueです。たとえば、ユーザーは温度を30分間、21度に設定できます。デフォルトはfalseです。 ブール値

検出応答の例

以下は、サーモスタットを制御し、Alexa.ThermostatControllerインターフェースとAlexa.TemperatureSensorインターフェースをサポートするAlexaスキルのDiscover.Responseメッセージの例です。この例のエンドポイントは、設定値が2つ、モードが3つのサーモスタットです。

クリップボードにコピーされました。

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "エンドポイントの一意のID",
                "manufacturerName": "エンドポイントのメーカー名",
                "description": "サーモスタットメーカー製のスマートサーモスタット",
                "friendlyName": "廊下のサーモスタット",
                "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
                "additionalAttributes": {
                    "manufacturer": "<エンドポイントのメーカー名>",
                    "model": "<デバイスのモデル>",
                    "serialNumber": "<デバイスのシリアル番号>",
                    "firmwareVersion": "<デバイスのファームウェアバージョン>",
                    "softwareVersion": "<デバイスのソフトウェアバージョン>",
                    "customIdentifier": "<デバイスのカスタム識別子>"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                    "name": "lowerSetpoint"
                                },
                                {
                                    "name": "upperSetpoint"
                                },
                                {
                                    "name": "thermostatMode"
                                },
                                {
                                    "name": "adaptiveRecoveryStatus"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": ["HEAT", "COOL", "AUTO"]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.TemperatureSensor",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "temperature"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

エアコン用の検出応答の例

通常、エアコンがサポートする設定値は1つで、モードは冷房のみです。サーモスタットは一般的に常時オンですが、エアコンはユーザーがオンとオフを切り替えます。エアコンの場合、Amazonでは、Alexa.PowerControllerインターフェースも実装し、次のリストのようにPowerControllerThermostatControllerを同期することをお勧めします。

  • サーモスタットのコントローラーモードがCOOLに設定されたら、電源コントローラーの電源状態をONにする。
  • サーモスタットのコントローラーモードがOFFに設定されたら、電源コントローラーの電源状態をOFFにする。

以下は、エアコンを制御し、ThermostatControllerインターフェースとAlexa.PowerControllerインターフェースをサポートするAlexaスキルのDiscover.Responseメッセージの例です。エアコンに温度を表示する場合を除き、Alexa.TemperatureSensorインターフェースの実装は不要です。

クリップボードにコピーされました。

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "エンドポイントの一意のID",
                "manufacturerName": "エンドポイントのメーカー名",
                "description": "スマートエアコン",
                "friendlyName": "リビングのエアコン",
                "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
                "additionalAttributes": {
                    "manufacturer": "<エンドポイントのメーカー名>",
                    "model": "<デバイスのモデル>",
                    "serialNumber": "<デバイスのシリアル番号>",
                    "firmwareVersion": "<デバイスのファームウェアバージョン>",
                    "softwareVersion": "<デバイスのソフトウェアバージョン>",
                    "customIdentifier": "<デバイスのカスタム識別子>"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                    "name": "targetSetpoint"
                                },
                                {
                                    "name": "thermostatMode"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": ["OFF", "COOL"]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

ディレクティブ

SetTargetTemperatureディレクティブ

SetTargetTemperatureディレクティブをサポートすると、サーモスタットに保持させたい温度をユーザーが設定できます。ユーザーは、オプションで新たな温度設定の期間を指定できます。

以下に、ユーザーの発話の例を示します。

アレクサ、寝室のサーモスタットを20に設定して
アレクサ、リビングのエアコンを24度に設定して

Alexa, set bedroom thermostat to twenty.
Alexa, set living room air conditioner to seventy-five.
Alexa, set the kitchen AC to twenty-five degrees for four hours.

SetTargetTemperatureディレクティブの例(設定値が1つのサーモスタット)

次の例は、Alexaがスキルに送信するSetTargetTemperatureディレクティブを示しています。


{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 20.0,
        "scale": "CELSIUS"
      }
    }
  }
}

SetTargetTemperatureディレクティブの例(設定値が2つのサーモスタット)

次の例は、設定値が2つのサーモスタット用にAlexaがスキルに送信するSetTargetTemperatureディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "lowerSetpoint": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
        "value": 72.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

SetTargetTemperatureディレクティブのペイロード

フィールド 説明
targetSetpoint サーモスタットは、温度をこの設定値に保持しようとします。ディレクティブには、設定値が1つのサーモスタット用に、このフィールドが含まれます。 Temperatureオブジェクト
lowerSetpoint サーモスタットは、温度をこの設定値より上に保持しようとします。ディレクティブには、設定値が2つのサーモスタット用に、このフィールドが含まれます。 Temperatureオブジェクト
upperSetpoint サーモスタットは、温度をこの設定値より下に保持しようとします。ディレクティブには、設定値が2つのサーモスタット用に、このフィールドが含まれます。 Temperatureオブジェクト
schedule サーモスタットが指定された設定値を保持する必要のある期間です。指定された期間で、新しい設定値が直ちに適用されます。このフィールドは、ユーザーが指定した場合にのみ含まれます(検出応答でサポートを示している必要があります)。 TimeIntervalオブジェクト

SetTargetTemperature応答

SetTargetTemperatureディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。

SetTargetTemperature応答イベントの例(設定値が1つのサーモスタット)

以下は、設定値が1つのサーモスタット用のSetTargetTemperature応答の例です。

クリップボードにコピーされました。

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
            "correlationToken": "<リクエストで受信した相関トークン>",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "エンドポイントID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.3,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 1000
            }
        ]
    }
}
SetTargetTemperature応答イベントの例(設定値が2つのサーモスタット)

以下は、設定値が2つのサーモスタット用のSetTargetTemperature応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "<リクエストで受信した相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "AUTO",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "lowerSetpoint",
        "value": {
          "value": 68.0,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "upperSetpoint",
        "value": {
          "value": 72.0,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 66.5,
          "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

SetTargetTemperatureディレクティブのエラー処理

SetTargetTemperatureディレクティブを正しく処理できなかった場合は、Alexa.ThermostatController.ErrorResponseイベントを使用して応答します。温度やサーモスタット特有のエラーではない場合は、汎用のAlexa.ErrorResponseイベントを使用して応答することもできます。

AdjustTargetTemperatureディレクティブ

AdjustTargetTemperatureディレクティブをサポートすると、サーモスタットに保持させたい温度をユーザーが調整できます。

以下に、ユーザーの発話の例を示します。

Alexa, make it warmer in here.
Alexa, make it cooler in here.

AdjustTargetTemperatureディレクティブの例

以下の例は、Alexaがスキルに送信するAdjustTargetTemperatureディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "AdjustTargetTemperature",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "targetSetpointDelta": {
        "value": -2.0,
        "scale": "CELSIUS"
      }
    }
  }
}

AdjustTargetTemperatureディレクティブのペイロード

フィールド 説明
targetSetpointDelta 温度の変化量です。変化量は正でも負でもかまいません。 Temperatureオブジェクト

AdjustTargetTemperature応答

AdjustTargetTemperatureディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。

以下は、設定値が1つのサーモスタット用のAdjustTargetTemperature応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "<リクエストで受信した相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

AdjustTargetTemperatureディレクティブのエラー処理

AdjustTargetTemperatureディレクティブを正しく処理できなかった場合は、Alexa.ThermostatController.ErrorResponseイベントを使用して応答します。温度やサーモスタット特有のエラーではない場合は、汎用のAlexa.ErrorResponseイベントを使用して応答することもできます。

SetThermostatModeディレクティブ

SetThermostatModeディレクティブをサポートすると、ユーザーがデバイスのモードを設定できます。ユーザーは、「アレクサ、[ユーザーのサーモスタットデバイス名]を[利用可能なモード]にして」のように言う必要があります。

SetThermostatModeディレクティブの例

次の例は、Alexaがスキルに送信するSetThermostatModeディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "thermostatMode" : {
        "value": "COOL"
      }
    }
  }
}

SetThermostatModeディレクティブのペイロード

フィールド 説明
thermostatMode サーモスタットに設定するモードです。 ThermostatModeオブジェクト

SetThermostatMode応答イベント

SetThermostatModeディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。

以下は、SetThermostatMode応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "<リクエストで受信した相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 17.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

SetThermostatModeディレクティブのエラー処理

SetThermostatModeディレクティブを正しく処理できなかった場合は、Alexa.ThermostatController.ErrorResponseイベントを使用して応答します。温度やサーモスタット特有のエラーではない場合は、汎用のAlexa.ErrorResponseイベントを使用して応答することもできます。

ResumeScheduleディレクティブ

ResumeScheduleディレクティブをサポートすると、ユーザーはサーモスタットにプログラムされているスケジュールを上書きした後に再開できます。たとえば、家を空けている間は休暇用の上書き設定を使用し、帰ってきたら通常のプログラムを再開する、という使い方ができます。

ResumeScheduleディレクティブの例

次の例は、サーモスタットのスケジュールを再開するためにAlexaがスキルに送信するResumeScheduleディレクティブを示しています。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ResumeSchedule",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {}
  }
}

ResumeScheduleディレクティブのペイロード

ResumeScheduleディレクティブのペイロードは定義されていません。

ResumeSchedule応答

ResumeScheduleディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、関連するすべてのプロパティの値を含めます。

以下は、ResumeSchedule応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "<リクエストで受信した相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 17.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

ResumeScheduleディレクティブのエラー処理

ResumeScheduleディレクティブを正しく処理できなかった場合は、Alexa.ThermostatController.ErrorResponseイベントを使用して応答します。温度やサーモスタット特有のエラーではない場合は、汎用のAlexa.ErrorResponseイベントを使用して応答することもできます。

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするために、ReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態および変更レポートについてを参照してください。

StateReport応答の例

以下は、StateReportディレクティブ応答の例です。

クリップボードにコピーされました。

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
            "correlationToken": "<リクエストで受信した相関トークン>",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2ベアラートークン"
            },
            "endpointId": "エンドポイントID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.9,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

エアコン用のStateReport応答の例

以下は、エアコンのStateReport応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "<リクエストで受信した相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2020-02-26T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2020-02-26T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
          "namespace": "Alexa.ThermostatController",
          "name": "adaptiveRecoveryStatus",
          "value": "INACTIVE",
          "timeOfSample": "2020-02-26T18:20:50Z",
          "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2020-02-26T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2020-02-26T18:20:50Z",
          "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

ChangeReportイベントの例

以下は、ChangeReportイベントの例です。

クリップボードにコピーされました。

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController",
            "name": "thermostatMode",
            "value": "COOL",
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ThermostatController",
            "name": "targetSetpoint",
            "value": {
              "value": 18.0,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.TemperatureSensor",
            "name": "temperature",
            "value": {
              "value": 19.1,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 1000
          }
        ]
      }
    }
  },
  "context": {
      "properties": [{
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2020-02-26T18:20:50Z",
          "uncertaintyInMilliseconds": 0
      }]
  }
}

エアコンのChangeReportイベントの例

以下は、エアコンのChangeReportイベントの例です。

クリップボードにコピーされました。

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2ベアラートークン"
            },
            "endpointId": "エンドポイントID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "RULE_TRIGGER"
                },
                "properties": [{
                        "namespace": "Alexa.ThermostatController",
                        "name": "thermostatMode",
                        "value": "COOL",
                        "timeOfSample": "2020-02-26T18:20:50Z",
                        "uncertaintyInMilliseconds": 500
                    },
                    {
                        "namespace": "Alexa.ThermostatController",
                        "name": "targetSetpoint",
                        "value": {
                            "value": 18.0,
                            "scale": "CELSIUS"
                        },
                        "timeOfSample": "2020-02-26T18:20:50Z",
                        "uncertaintyInMilliseconds": 500
                    },
                    {
                        "namespace": "Alexa.ThermostatController",
                        "name": "adaptiveRecoveryStatus",
                        "value": "PRECOOLING",
                        "timeOfSample": "2017-02-03T16:20:50.52Z",
                        "uncertaintyInMilliseconds": 1000
                    },
                    {
                        "namespace": "Alexa.TemperatureSensor",
                        "name": "temperature",
                        "value": {
                            "value": 19.1,
                            "scale": "CELSIUS"
                        },
                        "timeOfSample": "2020-02-26T18:20:50Z",
                        "uncertaintyInMilliseconds": 1000
                    }
                ]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

ユーザー確認の要求

ユーザーが温度を設定したり、サーモスタットのモード変更を指示した場合に、必要に応じてAlexaが実行する前にアクションを確認するようユーザーに要求できます。ユーザー確認を求めるには、Discover.Responseで確認を要求するディレクティブを指定します。詳細については、 verificationsRequiredオブジェクトユーザー確認を求めるサーモスタットの例を参照してください。

次に、ユーザ確認が必要な場合の会話の例を示します。

Alexa, set the temperature to sixty-five degrees on the living room air conditioner.
Set living room air conditioner to sixty-five degrees?
Yes.
OK, living room air conditioner is set to sixty-five degrees.

アレクサ、リビングのエアコンを25度にして。
リビングのエアコンで、設定温度を25度にするんですね?
はい。
リビングのエアコンを冷房25度に設定しました。