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

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

スマートホームデバイスを操作する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イベントに以下の情報を指定します。

  • プロパティ値が変更された理由を説明する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オブジェクトに、変更されたプロパティを含む取得可能なすべてのプロパティの状態をレポートします。
  • 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": []
    }
}

Last updated: Nov 08, 2022