Alexa.PowerLevelControllerインターフェース

Alexa.PowerLevelControllerインターフェース

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

このインターフェースは、調光スイッチなどの出力レベル制御をサポートするデバイスに使用します。パーセントで表せる一般的なプロパティの場合は、これではなくAlexa.PercentageControllerを実装します。

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

発話

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

Alexa, set the power to 40 percent on the fan.
Alexa, increase the power level by 12 on the light switch.

アレクサ、ファンの風量を40パーセントにして。
アレクサ、電気のスイッチでレベルを12にあげて。

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

プロパティ

powerLevelプロパティ

Alexa.PowerLevelControllerインターフェースは、powerLevelプロパティをプライマリプロパティとして使用します。このプロパティはデバイスの出力レベルを表し、0から100（両端の値を含む）の整数のパーセンテージで表現します。powerLevelプロパティを使用して変化を表す場合、有効値は-100～100（両端の値を含む）です。

検出

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

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

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

検出応答の例

以下は、Alexa.PowerLevelControllerインターフェースとAlexa.ColorControllerインターフェースをサポートする照明の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.PowerLevelController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerLevel"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ColorController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "color"
                  }
                ],
                "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"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

SetPowerLevelディレクティブ

ユーザーがデバイスの出力レベルを設定できるように、SetPowerLevelディレクティブをサポートします。

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

Alexa, set the power to 40 percent on the fan.

アレクサ、ファンの風量を40パーセントにして。

SetPowerLevelディレクティブペイロードの詳細

フィールド 説明 型
powerLevel デバイスに設定する出力レベルです。 整数

SetPowerLevelディレクティブの例

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

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

SetPowerLevel応答イベント

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

SetPowerLevel応答イベントの例

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "＜一意の識別子、バージョン4 UUIDが望ましい＞",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "＜エンドポイントID＞"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerLevelController",
        "name": "powerLevel",
        "value": 40,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

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

AdjustPowerLevelディレクティブ

ユーザーがデバイスの出力レベルを調整できるように、AdjustPowerLevelディレクティブをサポートします。

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

Alexa, increase the power level by 12 on the light switch.

アレクサ、電気のスイッチでレベルを12にあげて。

AdjustPowerLevelディレクティブペイロードの詳細

フィールド 説明 型
powerLevelDelta 出力レベルの変更量です。 整数

AdjustPowerLevelディレクティブの例

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

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

AdjustPowerLevel応答イベント

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

AdjustPowerLevel応答イベントの例

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "＜一意の識別子、バージョン4 UUIDが望ましい＞",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "＜エンドポイントID＞"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerLevelController",
        "name": "powerLevel",
        "value": 52,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

AdjustPowerLevelディレクティブを正しく処理できなかった場合は、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ベアラートークン>"
      },
      "endpointId": "＜エンドポイントID＞"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerLevelController",
        "name": "powerLevel",
        "value": 52,
        "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ベアラートークン>"
      },
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.PowerLevelController",
            "name": "powerLevel",
            "value": 75,
            "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
  }
}

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

最終更新日: 2022 年 07 月 04 日