状態および変更レポートについて



状態および変更レポートについて

スマートホームデバイスを操作するAlexaスキルを作成する際、状態および変更レポートのサポートを追加できます。Alexaは、音声応答、Alexaアプリのいずれかでデバイスの状態をユーザーに知らせます。たとえば、ユーザーはAlexaアプリでスマートプラグのリストを表示して、どのプラグがオンかオフかを確認できます。

Alexaに状態をレポートする方法は3つあります。

  • AlexaがReportStateディレクティブを使って状態をリクエストします。たとえば、ユーザーがAlexaアプリを開いてキッチンの照明がついているかどうかを確認するとします。すべてのプロパティ値のスナップショットを含むStateReportを返して応答します。
  • プロアクティブにChangeReportイベントを送信して1つ以上のプロパティが変更されたことを知らせます。イベントには、その他すべてのプロパティ値のスナップショットを含めることもできます。たとえば、ユーザーが手動で照明をつけたとします。イベントでは、電源がオンであることだけでなく、照明の明るさについてレポートすることもできます。
  • ディレクティブの応答ですべてのプロパティの状態をプロアクティブに送信します。たとえば、TurnOnディレクティブにすべてのプロパティ値のスナップショットを含めることができます。

状態および変更レポートのサポートを指定する

デバイスの検出中に、スキルでサポートするAlexaインターフェースを指定します。各インターフェースについて、検出応答で以下のプロパティを使い、状態および変更レポートのサポートを指定します。

  • Retrievable — retrievableプロパティは状態レポートを制御します。インターフェースにretrievable = trueを設定すると、Alexaはそのインターフェースの現在の状態をスキルに照会できます。AlexaがスキルにReportStateディレクティブを送信し、スキルがStateReportイベントで応答します。デフォルト値はfalseです。

  • ProactivelyReported — ProactivelyReportedプロパティは変更レポートを制御します。インターフェースにproactivelyReported = trueを設定すると、スキルはそのインターフェースのプロパティに何らかの変更があるたびに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": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "Smart Cooking Device Company",
          "description": "Brand XYZ oven",
          "friendlyName": "Oven",
          "displayCategories": ["OVEN"],
          "additionalAttributes":  {
            "manufacturer" : "Smart Cooking Device Company",
            "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": "battery"
                        },
                        {
                            "name": "radioDiagnostics"
                        },
                        {
                            "name": "networkThroughput"
                        }
                    ],
                    "proactivelyReported": true,
                    "retrievable": true
                }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

StateReportで状態をレポートする

Alexaがエンドポイントの状態をリクエストするReportStateディレクティブを送信した場合、StateReport応答を送信します。この応答には、取得可能なすべてのプロパティについて現在の状態を含めます。

たとえば、ユーザーがAlexaアプリで自宅の別の階にある照明の状態をチェックしたとします。Alexaは、その照明へのReportStateディレクティブを送信します。スキルは、その照明の取得可能なすべてのプロパティの状態を含む応答を送信し、アプリがその状態をユーザーにレポートします。

StateReportに以下の情報を指定します。

  • contextオブジェクトのすべてのretrievableプロパティの状態をレポートします。
  • endpointオブジェクトには必ずレポートするエンドポイントを指定します。
  • 必ずReportStateリクエストからの値を設定したcorrelationTokenを含めてください。

スキルのLambda関数から、同期的に応答イベントを送信できます。

スキルがエンドポイントを定期的にポーリングする場合、応答ではキャッシュされたプロパティ値を送信できます。エンドポイントに到達できなくても、すべてのプロパティ値がキャッシュされている場合は、すべてのプロパティ値を含むStateReportを返します。ただし、EndpointHealthのconnectivityプロパティの値はUNREACHABLEと指定してください。エンドポイントに到達できないためプロパティの状態を残らずレポートすることができず、値のキャッシュもない場合は、タイプがBRIDGE_UNREACHABLEまたはENDPOINT_UNREACHABLEErrorResponseを送信する必要があります。

ReportStateディレクティブの例

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

ReportStateディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa",
      "name": "ReportState",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {}
  }
}

StateReport応答の例

以下は、スキルがAlexaに送信するStateReport応答の例です。その他のStateReportの例については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。

StateReport応答の例

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<メッセージID>",
      "correlationToken": "<リクエストに一致するopaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "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
      }
    ]
  }
}

StateReportメッセージの詳細

プロパティ 説明

event

ヘッダーとエンドポイントの情報を定義します。

Eventオブジェクト

context

取得可能なすべてのプロパティの状態を含みます。

Contextオブジェクト

ChangeReportで状態をレポートする

エンドポイントの状態が何らかの理由で変化した場合、スキルはその変化をChangeReportイベントでAlexaにレポートします。その後、Alexaはユーザーにステータスの変更を提供できます。変更レポートでは、変化のあったプロパティの状態をpayloadオブジェクトに指定します。たとえば、ユーザーが照明を手動で点灯した場合は、Alexa.PowerControllerインターフェースのpowerStateプロパティの値がONに変更になったことを示す変更レポートイベントを送信します。

検出時にproactivelyReportedとしてプロパティを指定した場合、そのプロパティ値が変更されたときは必ずAlexaにChangeReportイベントを送信する必要があります。

状態の変化がAlexaからのディレクティブによるものの場合は、ディレクティブへの応答と変更レポートイベントの両方を送信します。詳細については、ディレクティブの応答で状態をレポートするを参照してください。

ChangeReportイベントに以下の情報を指定します。

  • プロパティ値が変更された理由を説明するcauseオブジェクトを含めます。
  • ChangeReportpayloadを使用して、新しいプロパティ値と、その変更の理由を提供します。propertiesの配列には、少なくとも1つのプロパティを含める必要があります。
  • 変更されなかったエンドポイントの残りすべてのプロパティの状態をレポートするには、ChangeReportcontextを使用します。これらのプロパティとその値をpropertiesの配列に列挙します。
  • 複数のプロパティが変更された場合は、ペイロードに1つのプロパティを入れた複数の変更レポートイベントを送信するか、ペイロードに複数のプロパティ値を入れた1つの変更レポートイベントを送信することができます。
  • endpointオブジェクトに、変更レポートを送信するユーザーとエンドポイントを必ず指定します。
  • correlationTokenを含めないでください。

ChangeReportイベントの例

以下は、Alexa.PowerControllerインターフェース、Alexa.BrightnessControllerインターフェース、 EndpointHealthインターフェースを実装した1つのエンドポイントに関するChangeReportイベントの例です。このイベントは、デバイスの物理的な操作によってエンドポイントのbrightness値が85%に変わったことをレポートしています。このイベントでは新しいbrightness値をpayloadに指定しているほか、値が変わらなかったことから、Alexa.PowerControllerプロパティとAlexa.EndpointHealthプロパティをcontextオブジェクトに指定しています。ChangeReportコードのその他の例については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。

ChangeReportイベントの例

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "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": "2021-11-15T14:20:00Z",
        "uncertaintyInMilliseconds": 60000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2021-11-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
    },
    {
        "namespace": "Alexa.EndpointHealth",
        "name": "battery",
        "value": {
            "health": {
                "state": "WARNING",
                "reasons": ["LOW_CHARGE"]
            },
            "levelPercentage": 45
        },
        "timeOfSample": "2021-11-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
    }
    ]
  }
}

ChangeReportメッセージの詳細

プロパティ 説明

event

ヘッダーとエンドポイントの情報、およびレポート可能なプロパティを定義します。

Eventオブジェクト

context

取得可能なすべてのプロパティの状態を含みます。

Contextオブジェクト

ディレクティブの応答で状態をレポートする

Alexaがプロパティの状態を変化させるディレクティブを送信し、スキルがそのディレクティブを正常に処理した場合、応答を送信します。応答では、変化のあったプロパティの状態をcontextオブジェクトに指定します。たとえば、AlexaがAlexa.PowerController.TurnOnディレクティブを送信すると、contextオブジェクトに新しい値ONを指定したpowerStateプロパティを含む応答イベントを送信します。

ディレクティブの応答に以下の情報を指定します。

  • contextオブジェクトに、変更されたプロパティを含む取得可能なすべてのプロパティの状態をレポートします。
  • endpointオブジェクトには必ずレポートするエンドポイントを指定します。ディレクティブのリクエストからの値を設定したcorrelationTokenを必ず含めてください。

Amazonでは、変化のなかったプロパティも含めてすべてのプロパティの状態を指定することをお勧めします。

応答イベントはスキルのLambda関数から同期的に送信するか、イベントゲートウェイから非同期的に送信します。

ディレクティブの例

以下は、Alexaがスキルに送信するディレクティブの例です。

ディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "AdjustPercentage",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
      "percentageDelta": -20
    }
  }
}

プロパティの状態を含むディレクティブの応答の例

以下は、スキルがAlexaに送信する応答の例です。

ディレクティブの応答の例

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "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に対して示すResponseイベントの例です。イベントのcontextの空のproperties配列により、変更後のプロパティの状態が判明していないことを示しています。

ディレクティブの応答の例

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

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "<メッセージID>",
            "correlationToken": "<opaque相関トークン>",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "<OAuth2ベアラートークン>"
            },
            "endpointId": "<エンドポイントID>"
        },
        "payload": {}
    },
    "context": {
        "properties": []
    }
}

ディレクティブの応答の詳細

プロパティ 説明

event

ヘッダーとエンドポイントの情報を定義します。

Eventオブジェクト

context

取得可能なすべてのプロパティの状態を含みます。

Contextオブジェクト

プロパティとオブジェクト

状態レポートのインターフェースは、以下のプロパティとオブジェクトを使用します。

Eventオブジェクト

Alexaへのすべての応答には、Eventオブジェクトが含まれます。

Eventオブジェクトの詳細

プロパティ 説明

header

メッセージヘッダーです。このフィールドには、イベント名、ペイロードのバージョン、メッセージID、相関トークンが含まれます。

Headerオブジェクト

endpoint

エンドポイントを指定し、スキルを認証する認可を提供します。

Endpointオブジェクト

payload

変更されたendpointプロパティと変更の理由です。
StateReportイベントとResponseイベントについては、空のオブジェクトを設定します。

Payloadオブジェクト

Contextオブジェクト

エンドポイントのすべてのレポート可能なプロパティを列挙するContextオブジェクトです。プロパティを追加するには、検出応答でretrievable = trueとしてプロパティを定義します。

Contextオブジェクトの詳細

プロパティ 説明

properties

エンドポイントの取得可能なプロパティを指定します。レポートされる各プロパティのPropertyオブジェクトを含めます。

Propertyオブジェクトの配列

Payloadオブジェクト

Payloadオブジェクトには、スキルがレポートする変更の理由と変更されたプロパティ値のリストを含めます。プロパティを追加するには、検出応答でproactivelyReported = trueとしてプロパティを定義します。Payloadオブジェクトには、変更されたプロパティ値のみを含めます。

Payloadオブジェクトの詳細

プロパティ 説明

change

変更の理由と変更されたプロパティのリストです。

Changeオブジェクト

Changeオブジェクト

変更されたプロパティと変更の理由をレポートするChangeオブジェクトを含めます。

Changeオブジェクトの詳細

プロパティ 説明

cause

1つ以上のプロパティの変更された理由です。

Causeオブジェクト

properties

変更されたレポート可能なプロパティのリストを指定します。変更をレポートするプロパティごとに1つのPropertyオブジェクトを含めます。

Propertyオブジェクトの配列

Propertyオブジェクト

Propertyオブジェクトは、エンドポイントのレポート可能なプロパティを定義します。各Alexaインターフェースでプロパティ名と値を定義します。詳細については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。

Propertyオブジェクトの詳細

プロパティ 説明

namespace

Alexa.PowerControllerなど、プロパティが属するAlexa機能インターフェースの名前です。

文字列

instance

(任意)汎用コントローラーのインターフェースについては、interfaceのインスタンスを指定します。たとえば、Dryer.Temperatureなどです。

文字列

name

namespaceに属するレポート対象プロパティの名前です。

文字列

value

レポートされるプロパティの値です。各Alexaインターフェースで、valueフィールドの型を定義します。
詳細については、スキルで使用する各インターフェースのドキュメントを参照してください。

バリエーション

timeOfSample

エンドポイントが状態変更を検出した時刻です。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

uncertaintyInMilliseconds

timeOfSampleフィールドの不確実性をミリ秒で指定します。
このフィールドは、エンドポイントが最後にプロパティ値を確認してからの経過時間(ミリ秒)を表します。たとえば、エンドポイントがプロパティ値のサンプリングを60秒前に行った場合、uncertaintyInMillisecondsには60000を設定します。

数値

Propertyオブジェクトの例

    "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2021-11-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
        },
        {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2021-11-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
        }
    ]

Causeオブジェクト

ChangeReportイベントの送信時にCauseオブジェクトを使ってプロパティ値変更の理由を説明します。

Causeオブジェクトの詳細

プロパティ 説明

type

変更の理由を指定します。

Type文字列

Causeオブジェクトの例

    "cause": {
          "type": "APP_INTERACTION"
    }

Type値

以下の表に、type値の説明を記載しました。

原因の種類 説明
APP_INTERACTION アプリを使ったユーザーの操作です。たとえば、ユーザーはAlexaアプリやデバイスベンダーのアプリを使って照明を点灯したり、ドアをロックしたりします。
PERIODIC_POLL エンドポイントの定期的なポーリングです。たとえば、温度センサーを1時間に1回ポーリングして、更新された温度をAlexaに送信できます。
PHYSICAL_INTERACTION エンドポイントの物理的な操作です。たとえば、ユーザーが手動で照明を点灯したり、ドアをロックしたりします。
RULE_TRIGGER デバイスのルールです。たとえば、ユーザーはモーションセンサーがモーションを検知した場合に照明を点灯するルールを設定します。この場合、Alexaはモーションセンサーからイベントを受信するとともに照明からも別のイベントを受信し、状態の変更がルールによって発生したことを示します。
VOICE_INTERACTION 音声対話です。たとえば、ユーザーがEchoデバイスに話しかけて照明を点灯します。