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

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

スマートホームデバイスを操作するAlexaスキルを作成するときは、状態レポートと変更レポートのサポートを追加します。Alexaは、音声応答、Alexaアプリ、画面付きのAlexa搭載デバイスのいずれかでデバイスの状態をユーザーに知らせます。たとえば、ユーザーはAlexaアプリでスマートプラグのリストを表示して、どのプラグがオンかオフかを確認できます。Amazon Echo Hubでは、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で応答し、その応答に各インターフェースのすべてのレポート可能プロパティの状態を含めます。retrievableをfalseに設定した場合は、ユーザーがデバイスの状態をたずねても、Alexaが正確な表示や応答を返すことはできません。

  • proactivelyReported - proactivelyReportedプロパティは変更レポートを制御します。インターフェースにproactivelyReported = trueを設定した場合、スキルは、そのインターフェースのレポート可能プロパティのいずれかに変更があるたびに（手動で変更された場合など）、Alexa.ChangeReportイベントをAlexaに送信します。Alexa.ChangeReportには、変更のないプロパティの状態も含めます。状態の変化がAlexaからのディレクティブによるものの場合は、ディレクティブへの応答と変更レポートイベントの両方を送信します。proactivelyReportedをfalseに設定した場合、Alexaは、デバイスの現在の状態をAlexaアプリまたは画面付きのAlexa搭載デバイス（Amazon Echo Hubなど）に表示することはできません。

  • 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.1",
                "properties": {
                    "supported": [{
                            "name": "connectivity"
                        }
                    ],
                    "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": "2023-07-03T10:20:50.52Z",
        "uncertaintyInMilliseconds": 6000
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2023-07-03T10:20:50.52Z",
        "uncertaintyInMilliseconds": 6000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2023-07-05T12:00:00.02Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

ChangeReportで状態をレポートする

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

検出時にインターフェースのプロパティをproactivelyReportedとして指定した場合、そのプロパティ値が変更されたときはAlexaにAlexa.ChangeReportイベントを送信する必要があります。状態の変化がAlexaからのディレクティブによるものの場合は、ディレクティブへの応答と変更レポートイベントの両方を送信します。Alexaでは、デバイスの状態の変更から3秒以内にChangeReportが送信されるものと想定しています。詳細については、ディレクティブの応答で状態をレポートするを参照してください。

Alexa.ChangeReportイベントを、非同期的にAlexaイベントゲートウェイに送信します。

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

  • プロパティ値が変更された理由を説明するcauseオブジェクトを含めます。
  • Alexa.ChangeReportのpayloadを使用して、新しいプロパティ値と、その変更の理由を提供します。payloadには、少なくとも1つのプロパティを含める必要があります。
    • エンドポイントでプロパティの状態が変更された時刻を表すtimeOfSampleを含めます。これはAlexa.ChangeReportイベントの送信時刻とは異なります。
  • 変更されなかったエンドポイントの残りすべてのプロパティの状態をレポートするには、Alexa.ChangeReportのcontextを使用します。これらのプロパティとその値をproperties配列に列挙します。
    • ここでは、プロパティごとに、そのプロパティで最後にレポートされた変更の時刻をtimeOfSampleとしてレポートします。
  • 複数のプロパティが変更された場合は、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": "2023-07-05T12:08:00.02Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2023-07-03T10:20:50.52Z",
        "uncertaintyInMilliseconds": 60000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2023-07-05T12:00:00.02Z",
        "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": "2023-07-01T12:01:00.02Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
            "value": "OK"
        },
        "timeOfSample": "2023-07-05T12:00:00.02Z",
        "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": []
    }
}

状態レポートに関するベストプラクティス

Alexaとデバイスアプリで一貫した正確なデバイスの状態がユーザーに通知されるようにするには、状態レポートに関するベストプラクティスに従ってください。レポートフローの詳細については、状態レポートの例を参照してください。

  • 検出応答では、スキルがサポートしているインターフェースごとに、レポート可能なプロパティをretrievable = trueおよびproactivelyReported = trueとしてマークします。
  • 制御ディレクティブに応答するときは、Alexa.Responseイベントのコンテキストで、Alexa.EndpointHealth.connectivityプロパティを含むすべての機能プロパティの状態を常にレポートします。
  • Alexaからのディレクティブによって状態の変更が発生した場合など、何らかの理由でいずれかのレポート可能なプロパティの状態が変更されたときは、Alexa.ChangeReportイベントを送信して、デバイスの状態をプロアクティブにAlexaにレポートします。
    • 変更されたプロパティについてのみtimeOfSampleを更新します。その他のプロパティでは、プロパティが最後に変更された時刻を表すtimeOfSampleをレポートします。同じtimeOfSample値をすべてのプロパティに設定しないでください。
  • 状態の変更から3秒以内に、新しいプロパティ値を含むAlexa.ChangeReportを送信します。Alexa.ChangeReportには、connectivityプロパティの現在値も含める必要があります。
  • Alexa.ChangeReportイベントがHTTPエラー503、429、401のいずれかで失敗した場合、またはメッセージがタイムアウトした場合は、少なくともあと2回、それぞれ15秒以内の間隔でAlexa.ChangeReportの再送信を試みます。
  • 状態のレポートでは、必ず同じデータ型と尺度を使用します。たとえば、StateReportで整数をレポートした場合は、Alexa.ChangeReportで浮動小数点数をレポートしないでください。または、Alexa.Responseで華氏温度をレポートした場合は、Alexa.ChangeReportで摂氏温度をレポートしないでください。このような誤りがあると、Alexaから送信されるReportStateメッセージが多くなり、スキルへのトラフィックが増加します。
  • スキルからのAlexa.StateReport応答とデバイス制御クラウドからのAlexa.ChangeReportとの間で、競合状態が発生することがあります。Alexaですべてのプロパティの状態が正しく表示されるようにするには、デバイスでプロパティ値が変更されたときにのみtimeOfSample値を更新します。たとえば、色を変更できる新しい照明があるとします。この照明では、次のようにtimeOfSampleをレポートします。
    • 午前8時0分、ユーザーが照明をつけます。powerState=ON、timeOfSample=2024-09-05T08:00:00Zをレポートします。
    • 午後12時0分、ユーザーはAlexaに照明を青くするように指示します。color(HSB)=Blue、timeOfSample=2024-09-05T12:00:00Zと、powerState=ON、timeOfSample=2024-09-05T08:00:00Zをレポートします。
    • 午後8時0分、ユーザーが照明を消します。powerState=OFF、timeOfSample=2024-09-05T20:00:00Zと、color(HSB)=Blue、timeOfSample=2024-09-05T12:00:00Zをレポートします。
    • 午後9時0分、ユーザーが照明をつけます。powerState=ON、timeOfSample=2024-09-05T21:00:00Zと、color(HSB)=Blue、timeOfSample=2024-09-05T12:00:00Zをレポートします。

状態レポートの例

以下では特定のデバイスタイプの状態レポートの例を示しますが、これらの例はほとんどのデバイスタイプに適用されます。

スマートロックの例

次の例は、ユーザーによるスマートロックの操作を示しています。このデバイスでは、ロックの状態とエンドポイントの健全性の各機能がレポートされます。

シナリオの流れ 対話タイプ スキル／デバイス制御クラウドのメッセージ よくある間違い

ユーザーが新しいスマートロックを入手します。

Alexaアプリでのデバイスの追加。

AlexaはAlexa.Discovery.Discoverをスキルに送信します。

スキルはAlexa.Discovery.Discover.Responseで応答し、すべてのレポート可能プロパティについて以下をtrueに設定します。

  • proactivelyReported=true
  • retrievable=true

スキルが、すべての機能のすべてのレポート可能プロパティをtrueに設定していない。応答の例については、検出応答の例を参照してください。

ユーザーがロックを解錠します。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドは、変更されたプロパティと変更のないプロパティを含むAlexa.ChangeReportを送信します。
payloadには変更されたプロパティが含まれます。

  • lockState=UNLOCKED

contextには変更のないレポート可能プロパティが含まれます。

  • connectivity=OK

Alexa.ChangeReportにAlexa.EndpointHealth.connectivityプロパティが含まれていない。

ユーザーがAmazon Echo Hubでロックのデバイスの状態を確認します。

Alexaのポーリング。

AlexaはAlexa.ReportStateをスキルに送信します。

スキルはAlexa.StateReportで応答します。
contextには以下が含まれます。

  • lockState=UNLOCKED
  • connectivity=OK

状態レポートは前回の変更レポートと一致する必要があります。一致しない場合、差異を解消する必要があります。不一致の問題をモニタリングするには、Alexa開発者コンソールで正確率メトリクスを確認します。

ユーザーがロックを施錠しますが、ロックが機能しません。

音声対話。

AlexaはAlexa.LockController.Lockをスキルに送信します。

スキルはAlexa.Responseで応答します。
contextには以下が含まれます。

  • lockState=JAMMED
  • connectivity=OK

デバイス制御クラウドはAlexa.ChangeReportを送信します。
payloadには以下が含まれます。

  • lockState=JAMMED

contextには以下が含まれます。

  • connectivity=OK

スキルのディレクティブ応答に、すべてのレポート可能プロパティが含まれていない。
スキルはディレクティブに応答するが、デバイス制御クラウドがAlexaに変更をレポートしない。

ユーザーがロックの不具合を直します。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドはAlexa.ChangeReportをプロアクティブに送信します。
payloadには以下が含まれます。

  • lockState=LOCKED

contextには以下が含まれます。

  • connectivity=OK

ブリッジまたはデバイスがオフラインのときに、ユーザーがロックの不具合を解消しても、デバイス制御クラウドが最新の状態の変更レポートをすぐに送信しない。

ユーザーがAmazon Echo Hubでデバイスの状態を確認します。

Alexaのポーリング。

AlexaはAlexa.ReportStateをスキルに送信します。

スキルはAlexa.StateReportで応答します。
contextには以下が含まれます。

  • lockState=LOCKED
  • connectivity=OK

状態レポートは前回の変更レポートと一致する必要があります。一致しない場合、差異を解消する必要があります。不一致の問題をモニタリングするには、Alexa開発者コンソールで正確率メトリクスを確認します。

カラー電球の例

次の例は、ユーザーによる電球の操作を示しています。このデバイスでは、電源の状態、色、明るさ、色温度、エンドポイントの健全性の各機能がレポートされます。

シナリオの流れ 対話タイプ スキル／デバイス制御クラウドのメッセージ よくある間違い

ユーザーが新しい電球を入手します。

Alexaアプリでのデバイスの追加。

AlexaはAlexa.Discovery.Discoverをスキルに送信します。

スキルはAlexa.Discovery.Discover.Responseで応答し、すべてのレポート可能プロパティについて以下をtrueに設定します。

  • proactivelyReported=true
  • retrievable=true

スキルが、すべての機能のすべてのレポート可能プロパティをtrueに設定していない。応答の例については、検出応答の例を参照してください。

ブリッジ（必要な場合）と照明が正常な状態のときに、ユーザーがライトの明るさを50%に設定します。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドは、変更されたプロパティと変更のないプロパティを含むAlexa.ChangeReportを送信します。
payloadオブジェクトには変更されたプロパティが含まれます。

  • brightness=50

contextオブジェクトには変更のないレポート可能プロパティが含まれます。

  • powerState=ON
  • color Hue/Saturation/Brightness (HSB) =238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

Alexa.ChangeReportにAlexa.EndpointHealth.connectivityプロパティが含まれていない。
contextに、変更のないすべてのレポート可能プロパティが含まれていない。

ブリッジと照明が正常な状態のときに、ユーザーが照明を消します。

音声対話。

AlexaはPowerController.TurnOffをスキルに送信します。

スキルはAlexa.Responseで応答します。
contextにはすべてのレポート可能プロパティが含まれます。

  • powerState=OFF
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

デバイス制御クラウドはAlexa.ChangeReportをAlexaに送信します。
payloadには以下が含まれます。

  • powerState=OFF

contextには以下が含まれます。

  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

スキルのディレクティブ応答に、すべてのレポート可能プロパティが含まれていない。
スキルはディレクティブに応答するが、デバイス制御クラウドがAlexaに変更をレポートしない。

ユーザーがAmazon Echo Hubで照明のデバイスの状態を確認します。

Alexaのポーリング。

AlexaはAlexa.ReportStateをスキルに送信します。

スキルはAlexa.StateReportで応答します。
contextには以下が含まれます。

  • powerState=OFF
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

状態レポートは前回の変更レポートと一致する必要があります。一致しない場合、差異を解消する必要があります。不一致の問題をモニタリングするには、Alexa開発者コンソールで正確率メトリクスを確認します。

ブリッジまたは照明が正常な状態ではありません。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドはAlexa.ChangeReportをプロアクティブに送信します。
payloadには以下が含まれます。

  • connectivity=UNREACHABLE

contextには以下が含まれます。

  • powerState=OFF
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536

ブリッジまたはデバイスがオフラインになったときに、デバイス制御クラウドがAlexaに変更をレポートしない。

ブリッジが正常な状態でないときに、ユーザーが照明をつけます。

音声対話。

AlexaはAlexa.PowerController.TurnOnをスキルに送信します。

スキルはAlexa.ErrorResponseで応答します。

  • type=BRIDGE_UNREACHABLE

ブリッジまたはデバイスがオフラインのときに、スキルが適切なエラーコードを送信しない。

ブリッジと照明が再び正常な状態になります。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドはAlexa.ChangeReportをプロアクティブに送信します。
payloadには以下が含まれます。

  • connectivity=OK

contextには以下が含まれます。

  • powerState=OFF
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536

ブリッジまたはデバイスがオンラインに戻っても、デバイス制御クラウドが変更レポートを送信してAlexaに通知しない。

ユーザーが照明をつけます。

音声対話。

AlexaはAlexa.PowerController.TurnOnをスキルに送信します。

スキルはAlexa.Responseで応答します。
contextには以下が含まれます。

  • powerState=ON
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

デバイス制御クラウドはAlexa.ChangeReportを送信します。
payloadには以下が含まれます。

  • powerState=ON

contextには以下が含まれます。

  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

スキルのディレクティブ応答に、すべてのレポート可能プロパティが含まれていない。
スキルはディレクティブに応答するが、デバイス制御クラウドがAlexaに変更をレポートしない。

照明が正常な状態ではありません。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドはAlexa.ChangeReportをプロアクティブに送信します。
payloadには以下が含まれます。

  • connectivity=UNREACHABLE

contextには以下が含まれます。

  • powerState=OFF
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536

ブリッジまたはデバイスがオフラインになったときに、デバイス制御クラウドがAlexaに変更をレポートしない。

照明に到達できない状態のときに、ユーザーが照明を消します。

音声対話。

AlexaはAlexa.PowerController.TurnOff をスキルに送信します。

スキルは次のAlexa.ErrorResponseで応答します。

  • type=ENDPOINT_UNREACHABLE

デバイスがオフラインのときに、スキルが適切なエラーコードを送信しない。

ブリッジと照明が再び正常な状態になります。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドはAlexa.ChangeReportをプロアクティブに送信します。
payloadには以下が含まれます。

  • connectivity=OK

contextには以下が含まれます。

  • powerState=OFF
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536

ブリッジまたはデバイスがオンラインに戻っても、デバイス制御クラウドが変更レポートを送信してAlexaに通知しない。

ユーザーが照明をつけます。

音声対話。

AlexaはAlexa.PowerController.TurnOnをスキルに送信します。

スキルはAlexa.Responseで応答します。
contextには以下が含まれます。

  • powerState=ON
  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

デバイス制御クラウドはAlexa.ChangeReportを送信します。
payloadには以下が含まれます。

  • powerState=ON

contextには以下が含まれます。

  • brightness=50
  • color(HSB)=238.24/0/1
  • colorTemperatureInKelvin=6536
  • connectivity=OK

スキルのディレクティブ応答に、すべてのレポート可能プロパティが含まれていない。
スキルはディレクティブに応答するが、デバイス制御クラウドがAlexaに変更をレポートしない。

ユーザーが照明の色をマゼンタ（HSB： 277.0/0.8619/0.9373）に設定します。

音声対話。

AlexaはAlexa.ColorController.SetColorをスキルに送信します。

スキルはAlexa.Responseで応答します。
contextには以下が含まれます。

  • powerState=ON
  • brightness=50
  • color(HSB)=277.0/0.8619/0.9373
  • colorTemperatureInKelvin=6536
  • connectivity=OK

デバイス制御クラウドはAlexa.ChangeReportを送信します。
payloadには以下が含まれます。

  • color(HSB)=277.0/0.8619/0.9373

contextには以下が含まれます。

  • powerState=ON
  • brightness=50
  • colorTemperatureInKelvin=6536
  • connectivity=OK

スキルはディレクティブに応答するが、デバイス制御クラウドがAlexaに変更をレポートしない。

ユーザーが照明の明るさを75%に設定します。

物理的な操作またはデバイスとアプリの対話。

デバイス制御クラウドはAlexa.ChangeReportを送信します。
payloadには以下が含まれます。

  • brightness=75

contextには以下が含まれます。

  • powerState=ON
  • color(HSB)=277.0/0.8619/0.9373
  • colorTemperatureInKelvin=6536
  • connectivity=OK

スキルのディレクティブ応答に、すべてのレポート可能プロパティが含まれていない。
スキルはディレクティブに応答するが、デバイス制御クラウドがAlexaに変更をレポートしない。

ユーザーがAmazon Echo Hubでデバイスの状態を確認します。

Alexaのポーリング。

AlexaはAlexa.ReportStateをスキルに送信します。

スキルはAlexa.StateReportで応答します。
contextには以下が含まれます。

  • powerState=ON
  • brightness=75
  • color(HSB)=277.0/0.8619/0.9373
  • colorTemperatureInKelvin=6536
  • connectivity=OK

状態レポートは前回の変更レポートと一致する必要があります。一致しない場合、差異を解消する必要があります。不一致の問題をモニタリングするには、Alexa開発者コンソールで正確率メトリクスを確認します。

サンプルコード

次のサンプルコードでは、変更レポートをAlexaイベントゲートウェイに送信するようにスマートホームスキルを設定する方法を示しています。

このページは役に立ちましたか？

最終更新日: 2024 年 12 月 17 日