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



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

スマートホームスキルを開発しながら、次のオプションを使用しでデバッグできます。

  • 状態レポートのテストツール – このツールを使用して、スキルに関連付けられたスマートホームデバイスのプロパティや、スキルがそのプロパティを紹介するのか、プロアクティブにAlexaに報告されるのかを確認できます。
  • スマートホームライブデバッガー – この機能を使用して、Alexaがスキルに関連付けられたデバイスについて受信した、処理エラーを含むChangeReportイベントを確認できます。

これらのツールを使用すると、Alexa Skills Kit開発者コンソールへのサインインに使用したAmazonアカウント内のスキルに関連付けられたスマートホームデバイスに関する情報を確認できます。他のAmazonアカウントからの情報は表示されません。

状態レポートを使用したスマートホームスキルの開発の詳細については、次のトピックを参照してください。

 

概要

スマートホームデバイスのプロパティが変更されたときはスマートホームスキルからAlexaに通知する必要があります。スキルはAlexaのイベントゲートウェイにChangeReportイベントを送信してAlexaに通知します。詳細については、イベントゲートウェイにイベントを送信するを参照してください。AlexaがスキルにReportStateディレクティブを送信することもあります。この場合、スキルはStateReportで応答する必要があります。

状態レポートのテストツールおよびスマートホームライブデバッガーを使用すると、Alexaが把握しているスマートホームデバイスの状態やその理由を理解できます。特に、次の情報が判りやすくなっています。

状態レポートのテストツール

  • スマートデバイスのプロパティの現在の状態。
  • AlexaがReportStateディレクティブに対する応答で状態を受信したか。

スマートホームライブデバッガー

  • Alexaが受信したChangeReportイベント。
  • 受信したChangeReportイベントの処理エラー（ある場合）。
  • スマートデバイスのプロパティがChangeReportのpayloadで送信されたか、contextで送信されたか。

これらのツールを一緒に使用することで、スキルとAlexaのやり取りをより詳細に確認できます。

前提条件

このトピックのツール、テストのヒント、トラブルシューティングの提案を利用するには、スマートホームデバイスのプロパティが変更されたときに状態更新（ChangeReport）イベントをAlexaイベントゲートウェイに送信するスマートホームスキルがある必要があります。つまり、スマートデバイスがサポートするすべての機能について、検出の応答（Discover.Response）で"proactivelyReported": trueと示されるということです。スキルがプロアクティブなレポートをスマートデバイスの一部のプロパティでしかサポートしていない場合、このトピックで説明されるツールは使用できません。

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

状態レポートのテストツールを使用すると、スマートデバイスのプロパティの現在の状態がいつスキルに照会されるか、また、Alexaがスキルから送信されるプロアクティブなChangeReportイベントをいつ使用するかを確認できます。以下のセクションで使用方法について説明します。

ステップ1： ツールにアクセスする

状態レポートのテストツールへのアクセスをリクエストするには、次の手順に従います。

  1. Amazon開発者ポータルで、テストするスマートホームスキルに関連付けられている開発者アカウントを使用してサインインします。
  2. カスタマー詳細ページでカスタマーIDを書き留めます。必要なのはカスタマーIDで、ベンダーIDではありません。

  3. 開発者サポート用のお問い合わせページを開きます。お問い合わせフォームを使用して次の情報を送信します。カスタマーIDは前の手順で書き留めたカスタマーIDに置き換えてください。

    カテゴリー： Alexa

    お問い合わせ内容： 次のカスタマーIDについて、状態レポートのテストツールへのアクセスをリクエスト：カスタマーID

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

ステップ2： サインインしてスキルを有効にする

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

ウェブベースのAlexaアプリの地域とそれぞれのURLの一覧は以下のとおりです。

スマートホームスキルの有効化とアカウントリンクが完了していない場合は、どちらも実行します。方法については、スマートホームスキルの作成手順を参照してください。

ステップ3： 状態の情報を表示して把握する

Alexaアプリで、スマートホーム、デバイスの順に移動します。開発者アカウントでツールが有効になった場合は、各デバイスの詳細なデバッグ情報が表示されます。次の図は、サンプルのデバイスを示しています。

ツールのCapability statesの各行は、検出の応答でプロアクティブにレポート可能としてマークしたスマートデバイス機能（プロパティ）を表します。また、各プロパティの現在の状態、およびAlexaが状態を判断するためにスキルをクエリしたかどうかも表示されます。

たとえば、上記の図でWireless In-wall Dimmerデバイスのプロパティの状態は以下のとおりです。

  • connectivity： OK
  • brightness： 0
  • powerState： OFF

次の図は、機能の状態の行の各部分の説明です。

特にDeepQueryの値に注意してください。これは、プロアクティブな状態の更新（ChangeReport）イベントと他のイベントデータが使用されているかどうか、またはAlexaがこの値を取得するクエリを行ったかどうかを示すブール値です。

  • DeepQuery: False： Alexaがプロアクティブな状態の更新（ChangeReport）イベントを使用してプロパティの値を判断したことを示します。

  • DeepQuery: True： AlexaがReportStateディレクティブをスキルに送信したことを示します。プロパティの値は、スキルからの応答で送信されるStateReportイベントで受け取っています。

ステップ4： トラブルシューティング

プロアクティブな状態の更新（ChangeReportイベント）が適切に実装されているにもかかわらず、DeepQuery: Trueと指定されている場合は、以下の項目を確認してください。

  • 新たに検出されたデバイスでは、Alexaの状態のキャッシュが空になっている場合があります。ブラウザでAlexaアプリを更新してください。デバイスのプロパティがReportStateディレクティブ（"retrievable": falseの場合）に対する応答で送信されていない場合、ChangeReportを送信してキャッシュに入力する必要があります。
  • すべてのデバイスのプロパティで"proactivelyReported": trueになっていること、およびすべてのプロパティ値がレポートされるようになっていることを確認します。EndpointHealthインターフェースの接続プロパティもこれに含まれます。
  • レポート対象が、デバイスで定義されレポート可能なプロパティの値のみになっていることも確認します。たとえば、デバイスがBrightnessControllerインターフェースを実装している場合、brightnessDeltaはレポート可能なプロパティではないため、proactivelyReportedとしてレポートしません。
  • サーモスタットデバイスでは、デバイスの検出時にレポートされるすべてのサポート対象設定ポイントがAlexaでキャッシュされていることを確認するため、冷房／暖房モードと自動モードの切り替えが必要になる場合があります。

ステップ5： その他のテストを実施する

デバイスのすべてのプロパティがDeepQuery: Falseであることを確認したら、そのデバイスでプロアクティブな状態の更新が発生するすべてのシナリオをテストする必要があります。シナリオごとに、目的のプロパティ値が状態レポートのテストツールに表示されることを確認します。

テストが必要なシナリオを次にいくつか挙げます。

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

  • EndpointHealthのプロアクティブな状態が更新されるかどうかをテストします。方法としては、デバイスの電源を切り、デバイス接続のポーリング間隔またはハートビート間隔が過ぎるまで待機します。スキルから接続値が変更されたことが報告されたら、ブラウザを更新してAlexaアプリでデバイスの状態を確認します。次に、再度デバイスの電源を入れて、Alexaアプリですべてのプロパティが正常に更新されることを確認します。

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

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

    このシナリオをテストするには、ツールを使用できるAmazonアカウントが少なくとも2つ必要です。追加のアカウントを有効にする必要がある場合は、ステップ1を参照してください。問い合わせフォームを送信する前に、必ず有効にするアカウントでログインしてください。

  • ログの応答を確認して、プロアクティブな状態の更新がAlexaイベントゲートウェイに正しく送信されていることを確認します。

状態レポートのテストツールで問題が発生した場合は、開発者サポート用のお問い合わせフォームを使用してご連絡ください。

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

スマートホームライブデバッガーを使用して、スマートホームデバイスに関連付けられたChangeReportイベントを確認できます。

ステップ1： ツールにアクセスする

スマートホームデバイスに関連付けられたChangeReportイベントを確認するには、次の手順を実施します。

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

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

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

  4. ページ上部で、デバイスのログおよびAlexaスマートホーム（ベータ）が選択されていることを確認します。

  5. ページのスマートホーム（ベータ）セクションで、スマートホームライブデバッガーを有効にするのトグルがオンになっていることを確認します。

Alexaがスマートホームスキルに関連付けられたスマートホームデバイスかのChangeReportイベントを受信すると、イベント情報がデバイスのログに追加されます。たとえば、次の図のようになります。

スマートホームライブデバッガー
スマートホームライブデバッガー

デバイスのログに表示されるChangeReportイベントについて詳しく知るには、次のセクションを参照してください。

スマートホームライブデバッガーで問題が発生した場合は、開発者サポート用のお問い合わせフォームを使用してご連絡ください。

ステップ2： ChangeReportイベントについて

前のセクションの手順を完了すると、Alexa Skills Kit開発者コンソールへのサインインに使用したAmazonアカウントのスマートホームスキルに関連付けられたスマートホームデバイスに関してAlexaが受信したChangeReportイベントがデバイスのログに表示されます。別のAmazonアカウントのデバイスのChangeReportイベントは表示されません。デバイスのログの各イベントには、Alexaが受信したChangeReportに関する詳細が記載されたJSONドキュメントが含まれています。

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

スキルがゲートウェイから202 Accepted応答を受信した場合でも、Alexaが正しく処理できないエラーがChangeReportで発生する場合があります。このような処理エラー（ある場合）は、デバイスのログで確認できます。考えられるエラーの完全なリストについては、以下のセクションを参照してください。

ChangeReportの処理エラー

次の表に、スマートホームライブデバッガーに表示される可能性のある処理エラーとその理由をリストします。ChangeReportイベントスキーマの詳細については、ChangeReportを参照してください。

エラーコード 理由
BEARER_TOKEN_NULL_OR_EMPTY ベアラートークンがないか、空です。
CAUSE_NULL payloadのcauseオブジェクトがありません。
CAUSE_TYPE_NULL_OR_EMPTY causeオブジェクトのcauseタイプがないか、タイプが空です。
CLIENT_ID_NOT_AVAILABLE クライアントID（カスタマーID）がありません。
CONTEXT_NULL contextオブジェクトがありません。
CONTEXT_PROPERTIES_EMPTY contextのpropertiesオブジェクトが空です。
CONTEXT_PROPERTIES_NULL contextのpropertiesオブジェクトがありません。
CONTEXT_PROPERTY_NULL contextのpropertiesオブジェクトのプロパティがありません。
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 payloadのpropertiesオブジェクトが空です。
PAYLOAD_PROPERTIES_NULL payloadのpropertiesオブジェクトがありません。
PAYLOAD_PROPERTY_NULL payloadのpropertiesオブジェクトのプロパティがありません。
REQUEST_NULL リクエストの本文がありません。
SCOPE_INVALID エンドポイントのスコープが無効です。
TIME_OF_SAMPLE_LARGER_THAN_THRESHOLD timeOfSampleフィールドに、ChangeReportの受信時刻より1秒以上遅い時刻が含まれています。
UNCERTAINTY_IN_MILLIS_LARGER_THAN_THRESHOLD uncertaintyInMillisecondsフィールドに14,400,000よりも大きい数値が含まれています。
UNKNOWN_PAYLOAD_VERSION ペイロードのバージョンがサポートされていません。
USER_IDENTIFIER_NULL_OR_EMPTY ユーザーIDがないか、空です。

スマートホームライブデバッガーのChangeReportイベントの例

ライブデバッガーで表示されるChangeReportイベントの例を次に示します。

ChangeReportイベント（成功）の例
{
  "header": {
    "customerId": "A1E2P2455A5NYT",
    "skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportSuccess",
    "messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
    "applianceId": "ALL"
  },
  "payload": {
    "request": {
      "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
          }
        ]
      },
      "event": {
        "header": {
          "messageId": "abc-123-def-456",
          "namespace": "Alexa",
          "name": "ChangeReport",
          "payloadVersion": "3"
        },
        "endpoint": {
          "endpointId": "endpoint-001",
          "cookie": {
            "path": "/path/for/this/endpoint"
          }
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      }
    }
  }
}
ChangeReportイベント（処理エラー）の例
{
  "header": {
    "customerId": "A1E2P2455A5NYT",
    "skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportFailure",
    "messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
    "applianceId": "ALL"
  },
  "payload": {
    "errors": [
      {
        "code": "Duplicate_Payload_Property",
        "message": "明るさのペイロードのプロパティを正しく複製してください"
      }
    ],
    "proactiveStateRequest": {
      "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
          }
        ]
      },
      "event": {
        "header": {
          "messageId": "abc-123-def-456",
          "namespace": "Alexa",
          "name": "ChangeReport",
          "payloadVersion": "3"
        },
        "endpoint": {
          "endpointId": "endpoint-001",
          "cookie": {
            "path": "/path/for/this/endpoint"
          }
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              },
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      }
    }
  }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment