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



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

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

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

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

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

前提条件

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

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

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

状態レポートのテストツールを使って、開発者アカウントに登録したスマートホームデバイスプロパティの現在の状態と、現在のプロパティ値が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のリストは次のとおりです。

  2. アプリで、スキルを探します。
    1. スキルを選択し、スキルページの右上隅にある有効なスキルを選択します。
    2. 開発スキルまでスクロールして、スキルを見つけます。
  3. 有効にするを選択して、スキルを有効にします。スキルをデバイス制御クラウドにアカウントリンクするためのページにリダイレクトされます。後でアカウントリンクを削除する場合は、スキルタブでスキルを無効にしてください。

状態情報を確認する

状態情報を表示する方法

  1. Alexaアプリで、スマートホームデバイスの順に選択します。
  2. デバイスごとに、拡張デバイス情報を確認できます。情報は次のように表示されます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

イベントを確認する

スマートホームライブデバッガーに、Alexa Skills Kit開発者コンソールへのサインインに使用したAmazonアカウントについて、Alexaがスキルから受信したChangeReportAddOrUpdateReportDeleteReportのイベントが表示されます。デバイスログの各イベントには、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イベントゲートウェイにChangeReportAddOrUpdateReportDeleteReportのいずれかのイベントが送信されると、ゲートウェイからHTTP応答を受け取ります。考えられるHTTP応答の完全なリストについては、イベントゲートウェイにイベントを送信するを参照してください。

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

SmartHomeChangeReportFailureのエラーコード

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

エラーコード 説明
BEARER_TOKEN_NULL_OR_EMPTY ベアラートークンがないか、空です。
CAUSE_NULL payloadcauseオブジェクトがありません。
CAUSE_TYPE_NULL_OR_EMPTY causeオブジェクトにcauseのタイプがないか、タイプが空です。
CLIENT_ID_NOT_AVAILABLE クライアントID(カスタマーID)がありません。
CONTEXT_NULL contextオブジェクトがありません。
CONTEXT_PROPERTIES_EMPTY contextpropertiesオブジェクトが空です。
CONTEXT_PROPERTIES_NULL contextpropertiesオブジェクトがありません。
CONTEXT_PROPERTY_NULL contextpropertiesオブジェクトのプロパティがありません。
DIRECTED_USER_ID_NULL_OR_EMPTY 指示されたユーザーIDがないか、空です。
DUPLICATE_CONTEXT_PROPERTY contextに同一のプロパティが2つあります。
DUPLICATE_PAYLOAD_PROPERTY payloadに同一のプロパティが2つあります。
DUPLICATE_PROPERTY_MISMATCHED_VALUE 単一のプロパティが異なる値で2度レポートされました。
ENDPOINT_ID_BLANK エンドポイントIDが空です。
ENDPOINT_ID_NULL エンドポイントIDがありません。
ENDPOINT_SCOPE_NULL エンドポイントのスコープがありません。
EVENT_ENDPOINT_NULL イベントエンドポイントがありません。
EVENT_HEADER_NULL イベントヘッダーがありません。
EVENT_NULL イベントオブジェクトがありません。
EVENT_PAYLOAD_NULL イベントペイロードがありません。
HEADER_NAME_NULL イベントオブジェクトのヘッダー名がnullです。
HEADER_NAMESPACE_NULL イベントオブジェクトのヘッダー名前空間がnullです。
HEADER_PAYLOAD_VERSION_NULL イベントオブジェクトのヘッダーのペイロードバージョンがnullです。
INVALID_ASYNC_EVENT 非同期応答に相関トークンがありません。
INVALID_CHANGE_REPORT ChangeReportに相関トークンが含まれています。ChangeReportには相関トークンが含まれてはいけません。
INVALID_HEADER_NAMESPACE ヘッダー名前空間には値Alexaが含まれている必要があります。
INVALID_PAYLOAD ペイロードを処理できませんでした。
INVALID_PAYLOAD_VERSION ペイロードを処理できませんでした。
INVALID_PROPERTY プロパティが無効です。
MISSING_TIME_OF_SAMPLE propertiesオブジェクトのtimeOfSampleフィールドがありません。
MISSING_UNCERTAINTY_IN_MILLIS propertiesオブジェクトのuncertaintyInMillisecondsフィールドがありません。
NEGATIVE_TIME_OF_SAMPLE_DIFFERENCE timeOfSampleフィールドに、ChangeReportの受信時刻よりも遅い時刻が含まれています。
NEGATIVE_UNCERTAINTY_IN_MILLIS uncertaintyInMillisecondsフィールドに負の数値が含まれています。この数値は正である必要があります。
PAYLOAD_PROPERTIES_EMPTY payloadpropertiesオブジェクトが空です。
PAYLOAD_PROPERTIES_NULL payloadpropertiesオブジェクトがありません。
PAYLOAD_PROPERTY_NULL payloadpropertiesオブジェクトのプロパティがありません。
REQUEST_NULL リクエストの本文がありません。
SCOPE_INVALID エンドポイントのスコープが無効です。
TIME_OF_SAMPLE_LARGER_THAN_THRESHOLD timeOfSampleフィールドに、ChangeReportの受信時刻から3秒を超えて遅い時刻が含まれています。
UNCERTAINTY_IN_MILLIS_LARGER_THAN_THRESHOLD uncertaintyInMillisecondsフィールドに14,400,000よりも大きい数値が含まれています。
UNKNOWN_PAYLOAD_VERSION ペイロードのバージョンがサポートされていません。
USER_IDENTIFIER_NULL_OR_EMPTY ユーザーIDがないか、空です。

SmartHomeAddOrUpdateReportFailureのエラーコード

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

エラーコード 説明
INVALID_REQUEST_EXCEPTION リクエストは、次のいずれかの理由で無効です。
  • イベントのタイプがサポートされていません。
  • ペイロードのバージョンがありません。
  • ペイロードのバージョンがサポートされていません。
  • エンドポイントIDがありません。
  • フレンドリー名がありません。
  • 解析エラーが発生しました。

SmartHomeDeleteReportFailureのエラーコード

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

エラーコード 説明
INVALID_REQUEST_EXCEPTION リクエストは、次のいずれかの理由で無効です。
  • イベントのタイプがサポートされていません。
  • ペイロードのバージョンがありません。
  • ペイロードのバージョンがサポートされていません。
  • 解析エラーが発生しました。