Alexa.PowerControllerインターフェース



Alexa.PowerControllerインターフェース

AlexaスキルにAlexa.PowerControllerインターフェースを実装することで、ユーザーがスマートホームデバイスのオン/オフを切り替えることができます。スマートホームスキルの詳細については、スマートホームスキルAPIについてを参照してください。

PowerControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。

発話

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

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

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

Alexa, allume l’aspirateur.
Alexa, éteins les lumières.

アレクサ、<デバイス名>をつけて
アレクサ、<デバイス名>を消して

ユーザーがこのような発話をすると、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": "<エンドポイントのメーカー名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "リビングの照明",
          "displayCategories": ["LIGHT"],
          "additionalAttributes":  {
            "manufacturer": "<エンドポイントのメーカー名>",
            "model" : "<デバイスのモデル>",
            "serialNumber": "<デバイスのシリアル番号>",
            "firmwareVersion" : "<デバイスのファームウェアバージョン>",
            "softwareVersion": "<デバイスのソフトウェアバージョン>",
            "customIdentifier": "<デバイスのカスタム識別子>"
          },
          "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
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

TurnOnディレクティブ

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

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

Alexa, turn on the vacuum.

Alexa, Staubsauger einschalten.

Alexa, allume l’aspirateur.

アレクサ、掃除機をオンにして
アレクサ、<デバイス名>をつけて

TurnOnディレクティブの例

次の例は、Alexaがスキルに送信する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, éteins les lumières.
Alexa, éteins les lumières s'il te plaît.

アレクサ、電気を消して
アレクサ、<デバイス名>をオフにして

TurnOffディレクティブの例

次の例は、Alexaがスキルに送信するTurnOffディレクティブを示しています。

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

ユーザー確認の要求

ユーザーがデバイスをオンまたはオフにしようとしたときに、必要に応じてAlexaが実行する前にアクションを確認するようユーザーに要求できます。ユーザー確認を求めるには、Discover.Responseで確認を要求するディレクティブを指定します。詳細については、 verificationsRequiredオブジェクトユーザー確認を求めるサーモスタットの例を参照してください。

次に、ユーザ確認が必要な場合の会話の例を示します。

Alexa, turn on the living room air conditioner.
The living room air conditioner will be turned on.Do you want to continue?
Yes.
The living room air conditioner is turned on.

アレクサ、リビングのエアコンをつけて。
リビングのエアコンをつけるんですね?
はい。
リビングのエアコンをつけました。

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

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

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

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