※ このブログは「Best Practices to Accurately Send State and Change Reports for Your Smart Home Skill」の翻訳です。紹介している機能は日本語に対応していない場合があります。
スマートホームスキルを使えば、先回りしてさまざまな状況を予測できるエクスペリエンスを提供することで、ユーザーがエネルギーを効率的に利用したり、時間やお金を節約したり、自宅で安全に暮らしたりするお手伝いができます。Alexa Hunchesなどの機能は、異常が発生したスマートホームコネクテッドデバイスの状態を、Alexaが先回りして変更できるエクスペリエンスの1つです。たとえば、玄関の鍵をかけていない状態で、「アレクサ、おやすみ」と言ったとします。そんなときは、ユーザーの代わりにAlexaが鍵をかけてくれます。就寝時間にも点いたままの照明があった場合には、 普段一晩中点けたままにしない照明だけをAlexaが消してくれます。ユーザーの代わりにAlexaが行うこうしたエクスペリエンスを提供するには、エンドポイントの状態をプロアクティブに報告する必要があります。正確なデバイスの状態は、Alexaがユーザーに提供するすべてのプロアクティブなアンビエントテクノロジーの基本です。
Works with Alexa認定プログラムに参加している開発者は、エンドポイントの状態をプロアクティブに報告することが、認定を維持するための必須条件となっています。では、正確さをさらに高めるための12の推奨事項を紹介しましょう。
イベントを送信するためにはいくつかの手順を実行する必要があります。まず、イベントを有効にしてから、Alexa.Authorizationインターフェースを実装し、Alexaイベントゲートウェイにイベントを送信する権限をリクエストして、ユーザーごとに認証トークンを取得します。最後に、検出応答を更新する必要があります。
1. 開発者コンソールでAlexaイベントを有効にする
Alexaイベントゲートウェイにレポートを送信するには、スキル内でAlexaイベントを有効にする必要があります。イベントが有効になると、スキルは応答で状態情報を共有したり、状態イベントをプロアクティブに送信したりできるようになります。Alexaイベントを有効にすると、スキルは変更を有効にするため、新しい認定サイクルを経る必要があります。
Alexaイベントを有効にするには、Alexa開発者コンソールの権限タブに移動します。
スマートホームスキル：
マルチ機能スキル：
権限タブのクライアントIDとクライアントシークレットの値はどちらも、ユーザーのアクセストークンをリクエストする際に必要になるため、メモしておいてください。
詳細はこちら：https://developer.amazon.com/en-US/docs/alexa/smarthome/authenticate-a-customer-permissions.html
2. Alexaイベントゲートウェイに送信する非同期のメッセージを有効にする
スキルが変更レポートや状態レポートなどの非同期のメッセージをAlexaイベントゲートウェイに送信する（非同期の状態レポート送信を選択した場合）うえで、Alexa.Authorizationインターフェースは重要な役割を果たします。
このインターフェースを実装すると、Alexaは、ユーザーがアカウントリンクプロセスを実行するたびに、AcceptGrantディレクティブを送信します。
既存のスキルでプロアクティブなレポート送信を有効にすることを検討している場合にも、AlexaはAcceptGrantディレクティブを送信します。既にスキルを有効にしたすべてのユーザーについてAcceptGrantディレクティブを受信する間、スキルはバックフィルプロセスを実行します。スキルは、AcceptGrantメッセージを処理し、認証プロセスを実行する必要があります。
- バックフィルプロセスで問題が発生する場合：
問題が発生し、ユーザーに関連付けられたアクセストークンや更新トークンを失ってしまった場合は、オフサイクルのバックフィルプロセスを実行して新しいトークンをリクエストする必要があります。Amazonは、すべてのユーザーについてAcceptGrantディレクティブの再送信プロセスを繰り返します。
バックフィルプロセスの詳細はこちら：https://developer.amazon.com/en-US/docs/alexa/smarthome/authenticate-a-customer-permissions.html#requesting-new-authorization-codes
Alexa.Authorizationインターフェースの詳細はこちら：https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-authorization.html
1. 対象となるコントローラー
ほとんどのスマートホームAPIコントローラーは状態および変更レポートをサポートします。ただし、CameraStreamControllerはプロアクティブにレポート可能なプロパティを定義しないため、例外となります。これ以外のコントローラーを実装した場合は、状態および変更レポートを送信してください。
各スマートホームデバイスに、デバイスの接続状態をレポートするEndpointHealthを実装する必要があります。レポートを送信するタイミングについてのルールは、以下のセクションで説明します。
2. 検出応答を更新する
実装したすべての機能が状態および変更レポートをサポートすることを確認します。
検出応答の各インターフェースについて、状態および変更レポートのサポートを指定する必要があります。指定するには、retrievableとproactivelyReportedの両方をtrueに設定します。状態および変更レポートのサポートは、ユーザーに最高のプロアクティブエクスペリエンスを提供できるかどうかを左右するため、この設定は重要です。
赤外線通信やスリープ状態のデバイスなど、エンドポイントの中には状態および変更レポートをサポートできないものもありますが、ほとんどのデバイスは状態をサポートするため、retrievable = trueとproactivelyReported = trueを設定する必要があります。
詳細はこちら：https://developer.amazon.com/en-US/docs/alexa/smarthome/state-reporting-for-a-smart-home-skill.html
3. レポート送信のタイミング
以下は、レポートを送信する必要のあるタイミングとレポートの種類のユースケースです。
- 変更を検出したら、ChangeReportを送信します。
- ReportStateディレクティブからデバイスの状態に関するプロンプトが出たら、StateReportで応答します。
- Alexaがプロパティの状態を変更するディレクティブを送信したら、デバイスの状態を含むResponseで応答し、ChangeReportも送信します。同じイベントに対して複数の種類のレポートを送信する必要がある場合もあります。たとえば、Alexaが照明をオンにするディレクティブを送信した場合、スキルは新しい状態を設定したResponseで応答し、イベントを正常に処理したことを示します。イベントの理由に「VOICE_INTERACTION」を設定してChangeReportを送信します。
1. StateReportおよびChangeReportに適用されるルール
レポートする状態の値が正しく処理されるよう、以下の形式ルールを守る必要があります。
- 各StateReportおよびChangeReportに、エンドポイントIDとベアラートークンを含める必要があります。
- ユーザーの代わりに非同期応答（ChangeReportを含む）を送信するたびに、Alexaイベントゲートウェイに対するメッセージのscopeオブジェクトにユーザーのアクセストークン（更新トークン）を含めます。
- endpointオブジェクト内にエンドポイントIDを指定して送信します。各エンドポイントIDは一意である必要があります。メッセージで送信されるエンドポイントIDは、検出応答で共有されるIDと同じである必要があります。
- StateReportでは、常に各インターフェースの現在の状態をレポートします。変更された値だけを送信しないでください。
- ChangeReportには変更の理由（cause）が必要です。causeに指定できる値は、Alexaを使った音声対話またはアプリ操作、アプリを使ったアプリの操作、デバイスの物理操作、ルールによるトリガーの5つです。詳細はこちら：https://developer.amazon.com/en-US/docs/alexa/smarthome/state-reporting-for-a-smart-home-skill.html#cause-object
- ペイロード内では、新しいイベントのみをレポートします。変更レポートで状態をレポートできるセクションは2つあります。
- context：変更のなかった状態をレポートします。
- payload：状態の変更をレポートします。
例：開発者であるLightBulb Inc.は、電球を制御するスマートホームスキルで、EndpointHealthとPowerControllerをサポートしています。あるユーザーが、インターネットに接続され、Alexaで制御可能なLightBulb Inc.製の電球を持っています。
そのユーザーは、午前10時に「アレクサ、電球をつけて」とリクエストします。開発者LightBulb Inc.は、以下の値を設定してChangeReportを送信します。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {
"path": "path/for/this/endpoint"
}
},
"payload": {
"change": {
"cause": {
"type": "VOICE_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2021-06-03T16:00:50Z",
"uncertaintyInMilliseconds": 60000
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-06-03T16:00:50Z ",
"uncertaintyInMilliseconds": 0
}
]
}
}
接続ステータスは変更されていませんが、電球はオフからオンに変わりました。
1. 状態更新のレイテンシーを抑える
ディレクティブがクラウドに送信された瞬間からデバイスの状態が変更されるまで、ChangeReportイベントは3秒以内に受信する必要があります。
また、イベントレポートが正確に行われないとプロアクティブなスマートホーム機能のパフォーマンスが低下するため、正確な状態レポートも不可欠です。Alexaがエンドポイントに関するReportStateディレクティブを送信し、スキルがStateReportで応答すると、AmazonはStateReport内の値を直前のChangeReport内の値と比較します（下の正確度スコアを参照）。
イベントをよりすみやかに送信するための推奨事項をいくつか紹介します。
- フリートが状態の更新をクラウドに返せることを確認します。前述した5つの変更理由に基づいて、エンドポイントの変更を検知できる必要があります。フリートが頻繁な更新を共有できない場合は、クラウドからポーリングメカニズムを実装できます。
- ChangeReportは非同期にAlexaイベントゲートウェイに送信されます。このため、レイテンシーのベストプラクティスを検討する必要があります。ChangeReportをスマートホームスキルを利用できる地域に合ったイベントのエンドポイントに送信していることを確認します（例：ChangeReportは、Lambda関数と同じ地域のエンドポイントに対して、その地域のユーザーに代わって送信します）。
開発者ポータルの「レポート」タブで、スキルのパフォーマンスを確認します。
1. 98%超の正確度を維持する
Alexaは、プロアクティブな変更レポート、またはAlexaディレクティブから受け取った更新された状態を通じて、状態レポートで報告される値とエンドポイントがAlexaに報告した直前のプロパティ値を比較することにより、エンドポイント状態の正確度を測定します。 Alexaが状態レポートを受信すると、プロパティの値がエンドポイントについてAlexaが保持しているプロパティの値と比較されます。 すべての値が同じである場合、コントローラーごとの正確度メトリクスは100%となります。データの不一致が検出されると、パーセンテージは低くなります。
2. 開発者ポータルで正確度スコアを確認する
開発者コンソールで、公開中のスキルを選択してメトリクスにアクセスします。「運用メトリクス」で、「変更レポート」を選択します。ページには、変更および状態レポートを受信しているすべてのコントローラーのメトリクスが表示されます。
- 各コントローラーについて、7日間の平均が、98%以上であることを確認します。
以下は、状態および変更レポートでよくある問題とその解決策です。
1. コントローラーの平均が一貫して基準値以下の場合：デバイスの状態更新イベントを見落としているか、レポートしていない可能性があります。
- Alexaイベントゲートウェイに対するメッセージ送信のポーリングメカニズムやレイテンシーを確認します。
2. コントローラーのグラフが変更レポートダッシュボードに表示されない場合：状態イベントを送信していない可能性があります。
- 実施していない実装手順がある可能性があるため、上記のポイントを確認します。検出応答から着手しましょう。検出応答でエンドポイントが「proactivelyReported」および「retrievable」をサポートしていないことが判明した場合、状態および変更レポートは無視されます。
- ReportStateディレクティブに正しく応答していることを確認するため、「状態のレポート」タブも確認してください。
Now Available: Enable Alexa to Proactively Act on Hunches Without Customers Needing to Ask
Now Available: Enable Your Customers to Track and Manage their Devices’ Energy Usage with the Alexa Energy Dashboard
