スマートホームスキルの状態レポートについて



スマートホームスキルの状態レポートについて

スマートホームスキルを実装すると、Alexaのエンドポイントの状態を更新することができます。Alexaはこの情報を使用して、音声またはAlexaアプリで最新の状態を維持します

状態をレポートする方法

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イベントを使用して状態をレポートするを参照してください。

検出時に状態レポートのサポート状況を提示する

状態レポートを有効にするには、検出中にエンドポイントの各プロパティが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イベントを送信することもできますが、これは推奨されません。

以下は、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に送信できます。ただし、各インターフェースをチェックして非同期メッセージングがサポートされていることを確認する必要があります。

非同期で応答するようにスキルを設定する方法の詳細については、イベントゲートウェイにイベントを送信するを参照してください。

.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment