状態および変更レポートについて
スマートホームデバイスを操作するAlexaスキルを作成する際、状態および変更レポートのサポートを追加できます。Alexaは、音声応答、Alexaアプリのいずれかでデバイスの状態をユーザーに知らせます。たとえば、ユーザーはAlexaアプリでスマートプラグのリストを表示して、どのプラグがオンかオフかを確認できます。
Alexaに状態をレポートする方法は3つあります。
- Alexaが
Alexa.ReportState
ディレクティブを使って状態をリクエストします。たとえば、ユーザーがAlexaアプリを開いてキッチンの照明がついているかどうかを確認するとします。すべてのプロパティ値のスナップショットを含むAlexa.StateReport
を返して応答します。 - プロアクティブに
Alexa.ChangeReport
イベントを送信して1つ以上のプロパティが変更されたことを知らせます。イベントには、その他すべてのプロパティ値のスナップショットを含めることもできます。たとえば、ユーザーが手動で照明をつけたとします。イベントでは、電源がオンであることだけでなく、照明の明るさについてレポートすることもできます。 - ディレクティブの
Alexa.Response
ですべてのプロパティの状態をプロアクティブに送信します。たとえば、TurnOn
ディレクティブにすべてのプロパティ値のスナップショットを含めることができます。
状態および変更レポートのサポートを指定する
デバイスの検出中に、スキルでサポートするAlexaインターフェースを指定します。各インターフェースについて、検出応答で以下のプロパティを使い、状態および変更レポートのサポートを指定します。
-
Retrievable – retrievableプロパティは状態レポートを制御します。インターフェースに
retrievable = true
を設定すると、Alexaはそのインターフェースの現在の状態をスキルに照会できます。AlexaがスキルにAlexa.ReportState
ディレクティブを送信し、スキルがAlexa.StateReport
イベントで応答します。デフォルト値はfalseです。 -
ProactivelyReported – ProactivelyReportedプロパティは変更レポートを制御します。インターフェースに
proactivelyReported = true
を設定すると、スキルはそのインターフェースのプロパティに何らかの変更があるたびにAlexa.ChangeReport
イベントをAlexaに送信します。デフォルト値はfalseです。 -
Noncontrollable – ユーザーが変更できないエンドポイントプロパティは、
nonControllable
=true
に設定することでモデル化できます。たとえば、洗濯機が自動で洗い、すすぎ、脱水に移行する場合、洗浄サイクルの変更を許可せずに、現在の洗浄サイクルをユーザーにレポートできます。trueに設定すると、Alexaは状態を変更しません。デフォルト値はfalse
です。
検出応答の例
以下は、Alexa.Cooking
インターフェース、Alexa.Cooking.TemperatureSensor
インターフェース、Alexa.Cooking.TemperatureController
インターフェース、Alexa.EndpointHealth
インターフェースをサポートするオーブンのDiscover.Response
メッセージの例です(Alexa.Cookingインターフェースは日本未対応です)。その他の検出応答例については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "一意の識別子、バージョン4 UUIDが望ましい"
},
"payload": {
"endpoints": [
{
"endpointId": "エンドポイントの一意のID",
"manufacturerName": "スマートクッキングデバイスカンパニー",
"description": "XYZブランドのオーブン",
"friendlyName": "オーブン",
"displayCategories": ["OVEN"],
"additionalAttributes": {
"manufacturer" : "スマートクッキングデバイスカンパニー",
"model" : "サンプルモデル",
"serialNumber": "U11112233456",
"firmwareVersion" : "1.24.2546",
"softwareVersion": "1.036",
"customIdentifier": "サンプルカスタムID"
},
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.Cooking",
"version": "3",
"properties": {
"supported": [
{
"name": "cookingMode"
},
{
"name": "foodItem"
},
{
"name": "cookingTimeInterval"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedCookingModes": ["REHEAT", "DEFROST", "OFF"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.Cooking.TemperatureSensor",
"version": "3",
"properties": {
"supported": [
{
"name": "cookingTemperature"
}
],
"proactivelyReported": false,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.Cooking.TemperatureController",
"version": "3",
"properties": {
"supported": [
{
"name": "targetCookingTemperature"
},
{
"name": "preheatTimeInterval"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportsRemoteStart": false,
"supportedCookingModes": ["BAKE", "ROAST"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
},
{
"name": "radioDiagnostics"
},
{
"name": "networkThroughput"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
StateReportで状態をレポートする
AlexaがAlexa.ReportState
ディレクティブを送信してエンドポイントの状態をリクエストすると、スキルは Alexa.StateReport
応答を送信します。この応答には、取得可能なすべてのプロパティについて現在の状態を含めます。
たとえば、ユーザーがAlexaアプリで自宅の別の階にある照明の状態をチェックしたとします。Alexaは、その照明へのAlexa.ReportState
ディレクティブを送信します。スキルは、その照明の取得可能なすべてのプロパティの状態を含む応答を送信し、アプリがその状態をユーザーにレポートします。
Alexa.StateReport
応答に以下の情報を指定します。
context
オブジェクトのすべてのretrievableプロパティの状態をレポートします。endpoint
オブジェクトには、必ずレポートするエンドポイントを指定します。payload
に空のオブジェクトを設定します。- 必ず
Alexa.ReportState
リクエストからの値を設定したcorrelationToken
を含めてください。
状態レポートのプロパティについて詳しくは、Alexa.StateReportインターフェースを参照してください。
スキルのLambda関数から、同期的にAlexa.StateReport
応答を送信できます。8秒以内に返信してください。
スキルがエンドポイントを定期的にポーリングする場合、応答ではキャッシュされたプロパティ値を送信できます。エンドポイントに到達できなくても、すべてのプロパティ値がキャッシュされている場合は、すべてのプロパティ値を含むAlexa.StateReport
を返します。ただし、Alexa.EndpointHealth
のconnectivityプロパティの値はUNREACHABLE
と指定してください。エンドポイントに到達できないためプロパティの状態を残らずレポートすることができず、値のキャッシュもない場合は、タイプがBRIDGE_UNREACHABLE
またはENDPOINT_UNREACHABLE
のAlexa.ErrorResponse
を送信する必要があります。
ReportStateディレクティブの例
次の例は、Alexaがスキルに送信するAlexa.ReportState
ディレクティブを示しています。
{
"directive": {
"header": {
"namespace": "Alexa",
"name": "ReportState",
"messageId": "一意のバージョン4 UUID",
"correlationToken": "opaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0ベアラートークン"
},
"endpointId": "エンドポイントID",
"cookie": {}
},
"payload": {}
}
}
StateReport応答の例
以下は、スキルがAlexaに送信するAlexa.StateReport
応答の例です。その他のAlexa.StateReport
の例については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "一意の識別子、バージョン4 UUIDが望ましい",
"correlationToken": "リクエストに一致するopaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "エンドポイントID",
"cookie": {}
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 25.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 6000
},
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 6000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
ChangeReportで状態をレポートする
エンドポイントの状態が何らかの理由で変化した場合、スキルはその変化をAlexa.ChangeReport
イベントでAlexaにレポートします。その後、Alexaはユーザーにステータスの変更を提供できます。変更レポートでは、変化のあったプロパティの状態をpayload
オブジェクトに指定します。たとえば、ユーザーが照明を手動で点灯した場合は、Alexa.PowerControllerインターフェースのpowerState
プロパティの値がON
に変更になったことを示す変更レポートイベントを送信します。
検出時にインターフェースのプロパティをproactivelyReported
として指定した場合、そのプロパティ値が変更されたときはAlexaにAlexa.ChangeReport
イベントを送信する必要があります。状態の変化がAlexaからのディレクティブによるものの場合は、ディレクティブへの応答と変更レポートイベントの両方を送信します。詳細については、ディレクティブの応答で状態をレポートするを参照してください。
Alexa.ChangeReport
イベントを、非同期的にAlexaイベントゲートウェイに送信します。
Alexa.ChangeReport
イベントを送信するには、Alexaイベントゲートウェイにイベントを送信する権限をリクエストし、ユーザーごとに認証トークンを取得します。イベントメッセージのscope
にトークンを含めます。詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストとAlexa.Authorization
インターフェースを参照してください。Alexa.ChangeReport
イベントに以下の情報を指定します。
- プロパティ値が変更された理由を説明する
cause
オブジェクトを含めます。 Alexa.ChangeReport
のpayload
を使用して、新しいプロパティ値と、その変更の理由を提供します。payload
には、少なくとも1つのプロパティを含める必要があります。- 変更されなかったエンドポイントの残りすべてのプロパティの状態をレポートするには、
Alexa.ChangeReport
のcontext
を使用します。これらのプロパティとその値をproperties
配列に列挙します。 - 複数のプロパティを変更した場合、1つのプロパティ値を持つペイロードを含む、複数の変更レポートイベントを送信できます。逆に、複数のプロパティ値を持つペイロードを含む、1つの変更レポートイベントを送信することもできます。
endpoint
オブジェクトで変更レポートのエンドポイントを識別します。endpoint.scope
オブジェクトにアクセストークンを含めます。correlationToken
を含めないでください。
変更レポートのプロパティについて詳しくは、Alexa.ChangeReportインターフェースを参照してください。
ChangeReportイベントの例
以下は、Alexa.PowerController
インターフェース、Alexa.BrightnessController
インターフェース、Alexa.EndpointHealth
インターフェースを実装した1つのエンドポイントに関するAlexa.ChangeReport
イベントの例です。このイベントは、デバイスの物理的な操作によってエンドポイントのbrightness
値が85パーセントに変わったことをレポートしています。このイベントでは新しいbrightness
値をpayload
に指定しているほか、値が変わらなかったことから、Alexa.PowerController
プロパティとAlexa.EndpointHealth
プロパティをcontext
オブジェクトに指定しています。その他のAlexa.ChangeReport
の例については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "一意の識別子、バージョン4 UUIDが望ましい",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "エンドポイントID",
"cookie": {
"path": "path/for/this/endpoint"
}
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 60000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "battery",
"value": {
"health": {
"state": "WARNING",
"reasons": ["LOW_CHARGE"]
},
"levelPercentage": 45
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
ディレクティブの応答で状態をレポートする
Alexaがプロパティの状態を変化させるディレクティブを送信し、スキルがそのディレクティブを正常に処理した場合、Alexa.Response
を送信します。応答では、変化のあったプロパティの状態をcontext
オブジェクトに指定します。たとえば、AlexaがAlexa.PowerController.TurnOn
ディレクティブを送信すると、context
オブジェクトに新しい値ON
を指定したpowerState
プロパティを含む応答イベントを送信します。
Alexa.Response
に以下の情報を指定します。
context
オブジェクトに、変更されたプロパティを含む取得可能なすべてのプロパティの状態をレポートします。注: Amazonでは、変化のなかったプロパティも含めてすべてのプロパティの状態を指定することをお勧めします。endpoint
オブジェクトで応答のエンドポイントを識別します。- ディレクティブのリクエストの値を設定した
correlationToken
を含めます。 - 応答を非同期的に送信する場合は、エンドポイントの
endpoint.scope
オブジェクトにアクセストークンを含める必要があります。
応答イベントは、スキルのLambda関数から同期的に、またはAlexaイベントゲートウェイに非同期的に送信できます。応答のプロパティの詳細については、応答イベントを参照してください。
ディレクティブの例
以下は、Alexaがスキルに送信するディレクティブの例です。
{
"directive": {
"header": {
"namespace": "Alexa.PercentageController",
"name": "AdjustPercentage",
"messageId": "一意のバージョン4 UUID",
"correlationToken": "opaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0ベアラートークン"
},
"endpointId": "エンドポイントID",
"cookie": {}
},
"payload": {
"percentageDelta": -20
}
}
}
状態を含むディレクティブの応答の例
以下は、スキルがAlexaに送信する非同期応答の例です。この例には、context
オブジェクトの状態プロパティが含まれています。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "一意の識別子、バージョン4 UUIDが望ましい",
"correlationToken": "リクエストに一致するopaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0ベアラートークン"
},
"endpointId": "エンドポイントID"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"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
}
]
}
}
取得可能ではないプロパティのディレクティブ応答の例
スキルは、取得可能ではないプロパティを持つエンドポイントへのディレクティブを正常に処理した後、context
にプロパティを含まない応答を送信する必要があります。
以下は、TurnOn
ディレクティブが正常に処理されたことをAlexaに知らせる同期的なAlexa.Response
イベントの例です。イベントのcontext
の空のproperties
配列により、変更後のプロパティの状態が判明していないことを示しています。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "一意の識別子、バージョン4 UUIDが望ましい",
"correlationToken": "リクエストに一致するopaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "エンドポイントID"
},
"payload": {}
},
"context": {
"properties": []
}
}
関連トピック
- Lambda関数を追加する
- Alexaインターフェースとサポートしている言語の一覧
- イベントゲートウェイにイベントを送信する
- Smart Home Skill Sample: Send Change Report(GitHub)
最終更新日: 2022 年 11 月 08 日