Alexa.PowerControllerインターフェース 3

Alexa.PowerControllerインターフェース 3

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

PowerControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。メッセージプロパティの定義については、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 user identificationを使用するConnected Vehicleの場合は、検出レスポンスにdirectiveConfigurationsを含めて、認証の信頼レベルとポリシー名を設定します。詳細については、directiveConfigurationsを参照してください。

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

検出応答の例

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

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
    },
    "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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },            
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

Alexaは次のAlexa.PowerControllerインターフェースディレクティブをスキルに送信します。

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": "一意のバージョン4 UUID",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOnディレクティブのペイロード

TurnOnディレクティブは、ペイロードパラメータを定義しません。空のpayloadオブジェクトを含めます。

TurnOn応答

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

以下は、TurnOn応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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": "一意のバージョン4 UUID",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {}
  }
}

TurnOffディレクティブのペイロード

TurnOffディレクティブはペイロードを定義しません。空のpayloadオブジェクトを含めます。

TurnOff応答

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

以下は、TurnOff応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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": "一意の識別子、バージョン4 UUIDが望ましい",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T16:20:50.52Z",
    "uncertaintyInMilliseconds": 0
  }
}

ユーザー確認の要求

ユーザーがデバイスをオンまたはオフにしようとしたときに、必要に応じて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）認定は、製品にAlexaとの互換性があることを認定し、より使いやすいスマートホームエクスペリエンスを確実にユーザーに提供できるよう支援するプログラムです。WWA認定プログラムの詳細については、Works with Alexa認定の概要を参照してください。

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

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

このページは役に立ちましたか？

最終更新日: 2022 年 11 月 08 日