Alexa.PowerControllerインターフェース



Alexa.PowerControllerインターフェース

Alexa.PowerController機能インターフェースは、デバイスの電源の状態を制御およびレポートするために使用するメッセージを記述します。

PowerControllerインターフェースでサポートされているロケールの一覧については、機能インターフェースとサポートされているロケールの一覧を参照してください。

発話

Alexa.PowerControllerインターフェースを使用する場合、音声対話モデルはすでにビルドされています。以下に、ユーザーの発話の例を示します。

Alexa, turn on the vacuum.
Alexa, turn off the lights.

Alexa, das Vakuum einschalten.
Alexa, schalte das Licht aus.

Alexa, allumer le vide s'il te plaît.
Alexa, éteindre les lumières s'il te plaît.

アレクサ、<Device name>
アレクサ、<Device name>を消して

ユーザーがこのような発話をしたら、Alexaがそれに対応するディレクティブをスキルに送信します。

プロパティ

powerStateプロパティ

Alexa.PowerControllerインターフェースは、powerStateプロパティをプライマリプロパティとして使用します。有効な値はONまたはOFFです。

検出

Alexa.PowerControllerをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

Alexaからスキルに状態レポートリクエストが送信されるときにレポートするすべてのインターフェースとプロパティのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートするインターフェースとプロパティのproactivelyReportedをtrueに設定します。

表示カテゴリーの一覧は、表示カテゴリーを参照してください。

応答例

以下は、Alexa.PowerControllerインターフェースとAlexa.BrightnessControllerインターフェースをサポートする1つのエンドポイントに対するDiscover.Responseメッセージの例です。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "modelName": "<エンドポイントのモデル名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "<Alexaアプリに表示されているデバイス名>",
          "displayCategories": ["LIGHT"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.BrightnessController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "brightness"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

TurnOnディレクティブ

ユーザーがデバイスをオンにできるように、TurnOnディレクティブをサポートします。

以下は、ユーザーの発話の例です。

Alexa, turn on the vacuum.

Alexa, das Vakuum einschalten.

Alexa, allumer le vide s'il te plaît.

アレクサ、電気をつけて

TurnOnディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOn応答イベント

TurnOnディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、変更されたすべてのプロパティの値を含めます。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。

TurnOn応答イベントの例

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

TurnOnディレクティブのエラー処理

TurnOnディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

TurnOffディレクティブ

ユーザーがデバイスをオフにできるように、TurnOffディレクティブをサポートします。

以下は、ユーザーの発話の例です。

Alexa, turn off the lights.

Alexa, schalte das Licht aus.

Alexa, éteindre les lumières s'il te plaît.

アレクサ、電気を消して

TurnOffディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOff",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOff応答イベント

TurnOffディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、変更されたすべてのプロパティの値を含めます。

TurnOff応答イベントの例

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

TurnOffディレクティブのエラー処理

TurnOffディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするためにReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態レポートについてを参照してください。

StateReport応答イベントの例

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、スマートホームスキルの状態レポートについてを参照してください。

ChangeReportイベントの例

{  
  "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.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {}
}

Works with Alexa認定のガイドライン

Works with Alexa(WWA)認定は、応答性、信頼性、機能性の高い基準をクリアし、ユーザーに対して最高のスマートホームエクスペリエンスを保証する認定プログラムです。製品が認定されると、Amazonスマートホームストアと製品パッケージにWorks with Alexa認定バッジを貼付できます。詳細については、デバイスのWorks with Amazon Alexa認定を受けるを参照してください。

Alexa.PowerControllerを実装しているデバイスについては、WWA認定を申請する前に次の要件を満たしていることを確認する必要があります。

  • デバイスはユーザーのリクエストに2秒以内に応答する必要があります。所要時間が5秒を超える応答は遅延エラーとみなされます。
  • すべてのプロパティは状態レポートretrievable変更レポートproactivelyReportedである必要があります。
  • GitHubのWWA PowerControllerテストで提供されているすべてのテストケースを実行している必要があります。