スマートホームスキルの状態レポートについて
スマートホームスキルを実装すると、Alexaのエンドポイントの状態を更新することができます。Alexaはこの情報を使用して、音声またはAlexaアプリで最新の状態を維持します
- 状態をレポートする方法
- 検出時に状態レポートのサポート状況を提示する
- 応答イベント内のcontextオブジェクトを使用した状態のレポート
- Alexaのリクエストに対して状態をレポートする
- ChangeReportイベントを使用して状態をレポートする
- プロパティのスキーマ
- エンドポイントの状態を非同期でレポートする
状態をレポートする方法
Alexa Skills Kitスマートホームの機能インターフェースを使用して、スマートホームデバイス(エンドポイント)とそのプロパティを記述します。これらのプロパティの状態は、次のようにレポートに表示されます。
ディレクティブに対する応答
ディレクティブに対する応答でプロパティの状態をレポートする方法は2つあります。
Controlディレクティブに対する応答
Responseイベントを送信してリクエストが正常に完了したことを示す際に、変更されたプロパティがあれば応答のcontext
オブジェクトで状態もレポートします。変更された可能性のあるプロパティを追加で含めることもできます。
たとえば、TurnOnディレクティブに応答するときであれば、powerStateプロパティを含むResponse
イベントを送信します。任意でエンドポイントのすべてのプロパティの状態を含めることもできます。これによりユーザーのエクスペリエンスを向上させることができます。応答イベントはスキルのLambda関数から同期的に送信するか、イベントゲートウェイから非同期的に送信します。
ReportStateディレクティブに対する応答
Alexaがエンドポイントの状態をリクエストするReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。この応答には、retrievable
であるすべてのプロパティについて現在の状態を含めます。
たとえば、ユーザーがAlexaアプリを確認して、1つのエンドポイントの状態をクエリするようにAlexaに指示することが考えられます。これに対して、そのエンドポイントについてretrievable
なすべてのプロパティの状態を入れた応答を送信します。StateReport
は、スキルのLambda関数から同期的に送信することも、イベントゲートウェイから非同期で送信することもできます。
詳細については、Alexaのリクエストに対して状態をレポートするを参照してください。
変更レポートとして
何らかの理由でエンドポイントの状態が変更された場合は、その変更をChangeReportイベントでAlexaにレポートします。その後Alexaからユーザーに状態の変更を提供できます。
たとえば、照明がオンになった場合は、powerState
プロパティの値がON
に変更されたことを示す変更レポートをAlexaに送信します。この変更がAlexaからのディレクティブによって発生したものであれば、Response
とChangeReport
イベントの両方を送信します。また、他の(変更されていない)プロパティの状態を、context
オブジェクトに入れてレポートすることもできます。これは任意ですが、推奨です。
詳細については、ChangeReport
イベントを使用して状態をレポートするを参照してください。
ChangeReport
イベントを送信するには、ユーザーごとにイベントゲートウェイにイベントを送信するアクセス権限をリクエストして認証トークンを取得し、イベントメッセージのscope
に含める必要があります。詳細については、アクセス権限を設定してAlexaのユーザー認証を実現するおよびAlexa.Authorizationを参照してください。検出時に状態レポートのサポート状況を提示する
状態レポートを有効にするには、検出中にエンドポイントの各プロパティがretrievable
でありproactivelyReported
であるかどうかを示す必要があります。
- プロパティの
retrievable
の値がtrue
であれば、そのプロパティの現在の状態を照会できることを意味します。状態を照会するには、AlexaがReportStateディレクティブを送信し、スキルはStateReportで応答します。 - プロパティの
proactivelyReported
の値がtrue
であれば、何らかの理由でエンドポイントの状態が変更された場合に、そのエンドポイントのChangeReportイベントを送信することを意味します。
各プロパティでこれらの値の組み合わせが4通りあります。
プロパティ値 | 説明 |
---|---|
"proactivelyReported": true "retrievable": true
|
プロパティがこのような値を持つ場合、スキルがChangeReport イベントを送信し、プロパティは照会可能です。たとえば、状態を照会可能であり、またデバイスが物理的に操作されて状態が変化したときはChangeReport イベントを送信する電球などです。
|
"proactivelyReported": false "retrievable": true
|
プロパティがこのような値を持つ場合、スキルはChangeReport イベントを送信しませんが、ReportState ディレクティブには応答するため照会は可能です。たとえば、状態を照会可能ですが、物理的に操作されてもChangeReport イベントを送信しない電球などです。
|
"proactivelyReported": true "retrievable": false
|
プロパティがこのような値を持つ場合、スキルはChangeReport イベントを送信しますが、プロパティを照会することはできません。たとえば、通常は休止状態の低電力デバイスは照会できません。ただし、設定が変更されるとデバイスがアクティブになり、ChangeReport イベントが送信されます。
|
"proactivelyReported": false "retrievable": false
|
プロパティがこのような値を持つ場合、スキルはChangeReport イベントを送信せず、プロパティを照会することもできません。たとえば、赤外線通信を使用して制御されるデバイスがこれに当たります。赤外線は一方通行の制御メカニズムです。デバイスにコマンドを送信することはできますが、状態に関するメッセージを送信する仕組みはサポートしていません。また、状態を照会することもできません。
|
プロパティが定義された検出メッセージの例
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "abc-123-def-456"
},
"payload": {
"endpoints": [
{
"endpointId": "uniqueIdOfLight",
"friendlyName": "リビングの照明",
"description": "ユーザーに表示される説明です",
"displayCategories": [
"THERMOSTAT"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
},
{
"type": "AlexaInterface",
"interface": "Alexa.ColorTemperatureController",
"version": "3",
"properties": {
"supported": [
{
"name": "colorTemperatureInKelvin"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
}
]
}
]
}
}
}
次の点にご注意ください。
- プロパティで
retrievable
またはproactivelyReported
の値を指定しない場合、Alexaはデフォルトではそれらの値をfalse
とみなします。 properties
オブジェクトそのものがない場合、Alexaはデフォルトでretrievable
とproactivelyReported
の値をfalse
とみなします。- インターフェースに新しいプロパティやディレクティブが追加された場合、エンドポイントの検出時にそれらがサポートされていると指定される場合にのみ、Alexaはそれらを使用します。
詳細については、Alexa.Discoveryを参照してください。
応答イベント内のcontextオブジェクトを使用した状態のレポート
必須のcontextオブジェクトを使用して、任意のイベントメッセージでプロパティの状態をレポートします。contextには、propertyオブジェクトの配列とその現在の状態が含まれています。それらの値は、更新されている場合と、更新されていない場合があります。状態レポートをサポートするプロパティの詳細については、プロパティのスキーマを参照してください。
状態が変更されるディレクティブを受信した場合、状態情報をcontext
で送信することができます。たとえば、AlexaがTurnOn
ディレクティブを送信します。
{
"directive": {
"header": {
"namespace": "Alexa.PowerController",
"name": "TurnOn",
"payloadVersion": "3",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001"
},
"payload": {}
}
}
この場合は、TurnOn
ディレクティブをエンドポイントに適用し、エンドポイントのすべてのプロパティ値を含んだcontext
オブジェクトを含むResponse
イベントで応答します。
context
を含めた応答イベントを送信する場合は、エンドポイントのすべてのプロパティの状態をレポートする必要があります。このときレポートする値には、ディレクティブを処理した結果起こった全ての結果を含める必要があります。
次の例は、Alexa.PowerControllerインターフェースとAlexa.BrightnessControllerインターフェースを実装した1つのエンドポイントのプロパティに関するResponse
イベントのcontext
を示しています。このイベントには、ディレクティブに入っていた同じcorrelationToken
がメッセージヘッダーに含まれています。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Propertyオブジェクト
property
オブジェクトは、どのプロパティが変更されたか、その新しい値、およびいつ変更されたかを示します。検出時にエンドポイントでサポートされているプロパティを提示し、次にイベントで状態情報を含むプロパティを送信します。Response
イベントの場合は、context
で状態情報を持つすべてのプロパティを送信します。
フィールド | 説明 |
---|---|
namespace |
変更されたプロパティの名前空間です。 |
name |
変更されたプロパティの名前です。 |
value |
プロパティの新しい値です。 |
timeOfSample |
プロパティの値が変更された時刻です。ISO 8601形式のUTC時刻で指定します。例: 2018-10-09T19:36:13+00:00 |
uncertaintyInMilliseconds |
プロパティが最後に確認されてから経過した時間(ミリ秒)です。たとえば、この値を60秒前に取得した場合は、不確実な期間は60000となります。 |
retrievable
ではないpowerState
プロパティの応答例
スキルがretrievable
ではないプロパティを持つエンドポイントに対するディレクティブを正常に処理した後、スキルはcontext
にプロパティを含まないResponse
イベントを送信する必要があります。
以下は、TurnOn
ディレクティブが正常に処理されたことをAlexaに対して示すResponse
イベントの例です。イベントのcontext
の空のproperties
配列により、変更後のプロパティの状態が判明していないことが示されます。
{
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa.PowerController",
"name": "Response",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "endpoint-id"
},
"context": {
"properties": []
},
"payload": {}
}
}
Alexaのリクエストに対して状態をレポートする
状態レポートをリクエストするには、エンドポイントを指定するReportState
ディレクティブをAlexaから送信します。以下の例を参照してください。このようなメッセージを受け取った場合は、検出プロセス時にretrievalbe
と定義したすべてのプロパティの状態をレポートします。
ReportState
ディレクティブの例
{
"directive": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa",
"name": "ReportState",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "appliance-001",
"cookie": {},
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
}
},
"payload": {}
}
}
応答内でStateReport
を送信し、その中に、各機能インターフェースのレポート可能なプロパティとその現在の値をすべて入れたcontext
オブジェクトを組み込む必要があります。エンドポイントを定期的にポーリングしている場合は、キャッシュされたプロパティの値を送信できます。
その時エンドポイントに到達できなくても、すべてのエンドポイントのプロパティ値がキャッシュされているためレポートできる場合は、StateReport
を返してすべてのプロパティ値を含めることができます。ただし、EndpointHealth
のconnectivity
プロパティの値はUNREACHABLE
と指定されます。エンドポイントに到達できないためすべてのプロパティの状態をレポートできず、値のキャッシュもない場合、BRIDGE_UNREACHABLE
またはENDPOINT_UNREACHABLE
タイプのErrorResponseを送信する必要があります。
StateReport
イベントの例
{
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "abcdef-123456",
"namespace": "Alexa",
"name": "StateReport",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001",
"cookie": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 25.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 6000
},
{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 6000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
},
"payload": {}
}
}
ChangeReportイベントを使用して状態をレポートする
ChangeReportイベントは、Alexaに状態の変更をプロアクティブに通知し、Alexaアプリにデバイスの現在の状態を確実に反映するために送信します。たとえば、ユーザーが電球エンドポイントを手動で点灯した場合は、それをAlexaに通知するために、Alexa.PowerControllerインターフェースのpowerState
プロパティの値がON
に変更になったことを示すChangeReport
イベントを送信します。
変更レポートはイベントゲートウェイに送信します。これを行うには、イベントゲートウェイにイベントを送信するアクセス権限をリクエストしてユーザーごとに認証情報を保存し、ChangeReport
のscope
に含める必要があります。詳細については、アクセス権限を設定してAlexaのユーザー認証を実現するを参照してください。
検出時にproactivelyReported
として提示したプロパティは、そのプロパティ値が変更されたときにはいつでもAlexaにChangeReport
イベントを送信する必要があります。
ChangeReport
のpayload
を使用して、新しいプロパティ値と、その変更の理由を提供します。ChangeReport
のcontext
を使用して、変更に直接影響されない他の任意のプロパティの状態もレポートすることをお勧めします。これにより、デバイスのプロパティの状態を最新に保ち、ユーザーのエクスペリエンスを向上させることができます。- 変更により複数のプロパティが影響を受ける場合は、Alexaに対して、単一の
ChangeReport
イベントに複数のプロパティ値を持つpayload
を含めて送信できます。また、それぞれが単一のプロパティを持つpayload
を含んだ複数のChangeReport
イベントを送信することもできますが、これは推奨されません。
payload
またはcontext
のどちらか1か所でのみレポートします。両方を使用することはできません。以下は、Alexa.PowerController
インターフェースとAlexa.BrightnessController
インターフェースを実装した1つのエンドポイントに関するChangeReport
イベントの例です。このイベントは、エンドポイントのbrightness
値がデバイスを直接操作することによって85%に変更されたことをレポートし、電源状態には変更がなかったため、powerState
をcontext
オブジェクトに入れてレポートしています。
{
"event": {
"header": {
"messageId": "abc-123-def-456",
"namespace": "Alexa",
"name": "ChangeReport",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "endpoint-001",
"cookie": {
"path": "path/for/this/endpoint"
}
},
"context": {
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 60000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 85,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
}
}
ペイロードの詳細
ChangeReport
イベントのペイロードには、変更されたプロパティの配列の入ったChangeオブジェクトと、変更の理由を示すcauseオブジェクトを組み込みます。
Causeオブジェクト
cause
アトリビュートは、ChangeReport
イベントの送信時に、プロパティ値の変更の理由を記述するために使用されます。
原因の種類 | 説明 |
---|---|
APP_INTERACTION |
イベントの原因が、ユーザーによるアプリケーションの操作にあったことを示します。たとえば、ユーザーがAlexaアプリやデバイスベンダーが提供するアプリを使用して照明のスイッチを切り替えたりドアをロックした場合です。 |
PHYSICAL_INTERACTION |
イベントの原因が、エンドポイントの物理的な操作にあったことを示します。たとえば、照明を手動でオンにした場合や、ドアの鍵を手動でロックした場合があります。 |
PERIODIC_POLL |
イベントの原因が、エンドポイントの定期的なポーリングにより値の変更が検出されたためであることを示します。たとえば、温度センサーを1時間に1回ポーリングして、更新された温度をAlexaに送信する場合があります。 |
RULE_TRIGGER |
イベントの原因が、デバイスルールの適用によるものであることを示します。たとえば、モーションセンサーが動きを検出した場合に照明をオンにするようにユーザーがルールを設定している場合があります。この場合、Alexaはモーションセンサーからイベントを受信するとともに照明からも別のイベントを受信し、状態の変更がルールによって発生したことを示します。 |
VOICE_INTERACTION |
イベントの原因が、音声による操作にあったことを示します。たとえば、ユーザーがEchoデバイスに話しかけた場合などです。 |
プロパティのスキーマ
サポートされるプロパティの全種類のスキーマについては、プロパティのスキーマで説明しています。機能インターフェースからプロパティへのマッピングと、各プロパティからスキーマへのマッピングについては、各インターフェースのトピックで説明しています。
エンドポイントの状態を非同期でレポートする
状態情報を含むすべてのメッセージは非同期でAlexaに送信できます。ただし、各インターフェースをチェックして非同期メッセージングがサポートされていることを確認する必要があります。
非同期で応答するようにスキルを設定する方法の詳細については、イベントゲートウェイにイベントを送信するを参照してください。
.