スマートホームスキルのデバッグ



Alexaはエンドポイントの状態についての情報をリクエストするためにReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、スキルは応答としてStateReportイベントを送信します。また、ChangeReportイベント、ディレクティブ応答イベント、エラー応答イベントについても、プロアクティブにAlexaに対して状態をレポートします。プロアクティブにレポートするプロパティは検出応答で指定します。状態レポートの詳細については、状態レポートについてを参照してください。

スマートホームスキルを開発する際に、次の2つのツールを使って状態やその他のイベントをデバッグできます。

• 状態レポートのテストツール – スキルと開発者アカウントに関連付けられたスマートホームデバイスのすべてのプロパティについて、現在の値と、現在の値がStateReportリクエストからのものか、あるいはChangeReportなどのプロアクティブレポートからのものかを確認できます。
• スマートホームライブデバッガー – Alexaがスキルから受信するChangeReport、AddOrUpdateReport、DeleteReportのイベント（とすべての処理エラー）を確認できます。

Alexa Skills Kit開発者コンソールへのサインインに使うAmazonアカウントに関する情報を確認できます。他のAmazonアカウントからの情報は表示されません。

• 前提条件
• 状態レポートのテストツールを使用する方法
  • 状態レポートのテストツールにアクセスする
  • Alexaアプリでスキルを有効にする
  • 状態情報を確認する
  • 変更レポートの問題をトラブルシューティングする
  • 他のシナリオをテストする
• スマートホームライブデバッガーの使用方法
  • スマートホームライブデバッガーにアクセスする
  • イベントを確認する
  • イベントエラーについて
• 関連トピック

前提条件

状態レポートのテストツールを使用するには、スマートホームデバイスのプロパティが変更されたときにスマートホームスキルがAlexaにChangeReportイベントを送信する必要があります。デバイスがサポートするインターフェースで定義しているすべてのプロパティについて、検出応答でproactivelyReportedをtrueに設定する必要があります。スキルで一部のプロパティにのみプロアクティブレポートをサポートしている場合、状態レポートのテストツールを使用することはできません。

スマートホームライブデバッガーを使用するには、スマートホームスキルがAlexaにChangeReport、AddOrUpdateReport、DeleteReportのいずれかのイベントを送信する必要があります。

状態レポートのテストツールを使用する方法

状態レポートのテストツールを使って、開発者アカウントに登録したスマートホームデバイスプロパティの現在の状態と、現在のプロパティ値がStateReportからのものか、あるいはChangeReportなどのプロアクティブレポートからのものかを確認できます。

状態レポートのテストツールにアクセスする

状態レポートのテストツールにアクセスするには、Alexaチームにアクセスをリクエストしてください。

状態レポートのテストツールにアクセスする方法

1. テストするスマートホームスキルの開発者アカウントでAmazon開発者ポータルにサインインします。
2. カスタマー詳細ページでcustomer IDを書き留めます。必要なのは、vendor IDではなくcustomer IDです。
3. Alexa開発者向け問い合わせ窓口を開きます。
4. 大カテゴリーで、Alexaスキルの開発を選択します。
5. 小カテゴリーで、テストと呼び出しを選択します。
6. 件名には、Requesting access to the state reporting test toolと入力します。
7. お問い合わせ内容の詳細には、Requesting access to the state reporting test tool for customer ID <コピーしたcustomer ID>と記入します。

ツールへのアクセスが可能になった時点、または追加情報が必要な場合に、Amazonからご連絡します。

複数メンバーを登録した家族アカウントなど、それぞれ個別のAmazonアカウントから同じデバイスを操作するシナリオも考えられます。同じデバイスでスキルを有効にしたすべてのAmazonアカウントについてChangeReportイベントの送信をテストするには、複数のテストアカウントが必要です。上記の手順を2つ目以降のアカウントについても実施し、このシナリオをテストしてください。

Alexaアプリでスキルを有効にする

状態レポートのテストツールは、既存のウェブベースのAlexaアプリのアドオンです。必ず該当するリージョンのAlexaアプリを使用し、ツールへのアクセスをリクエストしたときと同じアカウントを使用してサインインするようにしてください。

Alexaアプリでスキルを有効にする方法

1. 利用しているリージョンでウェブベースのAlexaアプリにログインします。リージョンと対応するURLのリストは次のとおりです。

   • 米国：alexa.amazon.com
   • 英国：alexa.amazon.co.uk
   • ドイツ：alexa.amazon.de
   • 日本：alexa.amazon.co.jp
   • カナダ：alexa.amazon.ca
   • オーストラリア：alexa.amazon.com.au
   • インド：alexa.amazon.in
   • スペイン：alexa.amazon.es
   • フランス：alexa.amazon.fr
   • イタリア：alexa.amazon.it
   • メキシコ：alexa.amazon.mx
2. アプリで、スキルを探します。
   1. スキルを選択し、スキルページの右上隅にある有効なスキルを選択します。
   2. 開発スキルまでスクロールして、スキルを見つけます。
3. 有効にするを選択して、スキルを有効にします。スキルをデバイス制御クラウドにアカウントリンクするためのページにリダイレクトされます。後でアカウントリンクを削除する場合は、スキルタブでスキルを無効にしてください。

状態情報を確認する

状態情報を表示する方法

1. Alexaアプリで、スマートホーム、デバイスの順に選択します。

2. デバイスごとに、拡張デバイス情報を確認できます。情報は次のように表示されます。

   

   機能の状態の各行は、スマートデバイス機能インターフェースのプロパティを表します。各行には、次の情報が含まれます。

   • プロパティの名前と現在の値
   • プロパティの現在の値のタイムスタンプ
   • 現在のタイムスタンプが不確実な期間（ミリ秒）
   • DeepQuery - 最後に設定された値がStateReportからの場合はTrue、最後に設定された値がChangeReportなどのプロアクティブレポートからの場合はFalse

変更レポートの問題をトラブルシューティングする

スキルに変更レポートを実装している場合、状態レポートのテストツールのプロパティがDeepQuery: False（最後に設定された値がChangeReportであることを示す値）と表示される必要があります。

変更レポートを正常に実装しているにもかかわらず、DeepQuery: Trueと指定されている場合は、以下の項目を確認してください。

• 新たに検出されたデバイスでは、Alexaの状態のキャッシュが空になっている場合があります。ブラウザでAlexaアプリを更新してください。StateReportイベントを送信しない場合、ChangeReportを送信してキャッシュに書き込みます。

• すべてのデバイスのプロパティでproactivelyReportedがtrueになっていること、およびすべてのプロパティがChangeReportでレポートされるようになっていることを確認します。

• EndpointHealthインターフェースを実装している場合、connectivityプロパティをStateReport、ChangeReportの各イベントに含めてください。

• サポートするインターフェースで定義したプロパティのみがレポート対象になっていることを確認します。たとえば、ディレクティブのパラメーターをプロパティとしてレポートしないでください。詳細については、デバイスでサポートする各インターフェースのドキュメントを参照してください。

• ThermostatControllerインターフェースを実装しているスキルの場合、デバイスがサポートするサーモスタットモードをサイクルで切り替え、Alexaがデータをキャッシュできるようにします。

他のシナリオをテストする

デバイスのすべてのプロパティがDeepQuery: Falseであることを確認したら、ChangeReportイベントをトリガーするデバイスのシナリオをすべてテストします。シナリオごとに、目的のプロパティ値が状態レポートのテストツールに表示されることを確認してください。

以下に、テストが可能なシナリオをいくつか挙げます。

• Alexaを使用せずに、デバイスの状態を変更します。たとえば、別のアプリケーションや物理デバイスコントロールを使用して、デバイスのオン／オフを切り替えたり、設定を変更したりします。この操作によって、スキルからAlexaに1つ以上のChangeReportイベントが送信されます。ブラウザでAlexaアプリを更新し、DeepQuery: Falseになっていること、予想どおりのプロパティ値が表示されることを確認してください。

• EndpointHealthインターフェースを実装している場合、ChangeReportイベントでconnectivityプロパティが正しくレポートされていることを確認します。デバイスの電源を切り、デバイス接続のポーリング間隔またはハートビート間隔が過ぎるまで待機します。スキルから接続状態が変更されたことがレポートされたら、ブラウザを更新してAlexaアプリを確認します。その後、端末の電源を再度オンにし、Alexaアプリをもう一度確認してください。

  注： ツールでEndpointHealthのテスト時にスキルの応答がエラーの場合、問題が発生することがわかっています。ツールがErrorResponseを受け取ると、Failed to retrieve stateと表示され、それ以外の情報は表示されません。この問題が解決されるまで、このシナリオについては、適切なJSON形式の応答とエラーコードが送信されることをログで確認して検証してください。

• 最初のアカウントや最近のアカウントだけでなく、スキルの有効化とアカウントリンクを行ったすべてのAmazonアカウントで、ChangeReportイベントが送信されることを確認します。通常、家族のメンバーはスマートホームデバイスを共有しますが、それぞれがデバイスのスキルに関連付けられた個別のAmazonアカウントを所有しています。

  状態レポートのテストツールを使用すると、Alexa Skills Kit開発者コンソールへのサインインに使用したAmazonアカウント内のスキルに関連付けられたスマートホームデバイスに関する情報のみを確認できます。他のAmazonアカウントからの情報は表示されません。このシナリオをテストするには、同一のデバイスの資格情報を使用して、さまざまなAmazonアカウントからスキルの有効化とアカウントリンクを行います。その後、Alexaを使用せずにデバイスの状態を変更します。それぞれのAmazonアカウントにサインインし、状態レポートのテストツールを使用して、プロパティの状態が正しいこと、DeepQuery: Falseであることを確認します。これにより、各AmazonアカウントでChangeReportイベントが正しく送信されることを確認できます。

  注： AlexaにChangeReportイベントを送信するときに403 Forbiddenの応答を受け取った場合は、ユーザーがスキルを無効にしていることを意味しています。そのため、そのユーザーへのメッセージ送信は中止できます。

• ログの応答を調べて、Alexaに正しいChangeReportイベントを送信していることを確認します。

状態レポートのテストツールで問題が発生した場合は、Alexa開発者向け問い合わせ窓口ページから問い合わせてください。

スマートホームライブデバッガーの使用方法

スマートホームライブデバッガーを使用して、スマートホームデバイスに関連付けられたChangeReport、AddOrUpdateReport、DeleteReportの各イベントを確認できます。次の情報が表示されます。

• リクエストJSONなど、Alexaが受信するイベント
• イベントの処理エラー（ある場合）

スマートホームライブデバッガーにアクセスする

スマートホームライブデバッガーの使用方法

1. テストするスマートホームスキルの開発者アカウントでAmazon開発者ポータルにサインインします。

2. Alexa Skills Kit開発者コンソールを開きます。

3. スマートホームデバイスに関連付けられたスマートホームスキルを開きます。

4. テストページを開きます。

5. スキルのテストを有効にします。

6. ページ上部で、デバイスのログ、Alexaスマートホーム（ベータ）を選択します。

7. スマートホーム（ベータ）セクションで、スマートホームライブデバッガーを有効にします。

この手順を完了すると、AlexaへのChangeReport、AddOrUpdateReport、DeleteReportのイベント送信時に 、イベント情報がデバイスログに追加されます。

イベントを確認する

スマートホームライブデバッガーに、Alexa Skills Kit開発者コンソールへのサインインに使用したAmazonアカウントについて、Alexaがスキルから受信したChangeReport、AddOrUpdateReport、DeleteReportのイベントが表示されます。デバイスログの各イベントには、Alexaが受信したイベントに関する詳細が記載されたJSONドキュメントが含まれています。以下は、スマートホームライブデバッガーの図です。

スマートホームライブデバッガーで問題が発生した場合は、Alexa開発者向け問い合わせ窓口ページから問い合わせてください。

ChangeReportイベントが正常に処理された例

以下は、Alexaが正常に処理できたChangeReportイベントがスマートホームライブデバッガーに記録された例です。

{
  "header": {
    "customerId": "<カスタマーID>",
    “skillId”: “<スキルID>”,
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportSuccess",
    "messageId": "<メッセージID>",
    "applianceId": "ALL"
  },
  "payload": {
    "request": {
      "event": {
        "header": {
          "namespace": "Alexa",
          "name": "ChangeReport",
          "messageId": "<メッセージID>",
          "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "<OAuth2ベアラートークン>"
          },
          "endpointId": "<エンドポイントID>"
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      },
      "context": {
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

ChangeReportイベントがエラーになった例

以下は、リクエストにエラーが含まれているためにAlexaが正常に処理できなかったChangeReportイベントがスマートホームライブデバッガーに記録された例です。詳細については、イベントエラーについてを参照してください。

{
  "header": {
    "customerId": "<カスタマーID>",
    “skillId”: “<スキルID>”,
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportFailure",
    "messageId": "<メッセージID>",
    "applianceId": "ALL"
  },
  "payload": {
    "errors": [
      {
        "code": "Duplicate_Payload_Property",
        "message": "duplicate property in the payload for brightness property"
      }
    ],
    "proactiveStateRequest": {
      "event": {
        "header": {
          "namespace": "Alexa",
          "name": "ChangeReport",
          "messageId": "<メッセージID>",
          "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type": "BearerToken",
            "token": "<OAuth2ベアラートークン>"
          },
          "endpointId": "<エンドポイントID>"
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              },
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      },
      "context": {
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

イベントエラーについて

スキルからAlexaイベントゲートウェイにChangeReport、AddOrUpdateReport、DeleteReportのいずれかのイベントが送信されると、ゲートウェイからHTTP応答を受け取ります。考えられるHTTP応答の完全なリストについては、イベントゲートウェイにイベントを送信するを参照してください。

スキルがゲートウェイから202 Accepted応答を受信した場合、Alexaがイベントリクエストを正常に受信したことを意味します。ただし、イベントにAlexaの正常処理を妨げるエラーがある場合があります。この場合、ライブデバッガーのログに、ペイロードにエラーの配列を含むSmartHomeChangeReportFailure、SmartHomeAddOrUpdateReportFailure、SmartHomeDeleteReportFailureのいずれかのイベントが出力されます。

SmartHomeChangeReportFailureのエラーコード

次の表は、スマートホームライブデバッガーに表示される可能性のあるSmartHomeChangeReportFailureのエラーコードのリストです。

SmartHomeAddOrUpdateReportFailureのエラーコード

次の表は、スマートホームライブデバッガーに表示される可能性のあるSmartHomeAddOrUpdateReportFailureのエラーコードのリストです。

SmartHomeDeleteReportFailureのエラーコード

次の表は、スマートホームライブデバッガーに表示される可能性のあるSmartHomeDeleteReportFailureのエラーコードのリストです。

関連トピック

• スマートホームスキルの作成手順
• イベントゲートウェイにイベントを送信する