Alexa.BrightnessControllerインターフェース



Alexa.BrightnessControllerインターフェース

Alexa.BrightnessControllerインターフェースには、電球などのエンドポイントの輝度を制御するために使用されるメッセージが含まれます。このインターフェースは、輝度の調整に対応しているデバイスに対して、より汎用的なAlexa.PercentageControllerインターフェースの代わりに使用するようにします。調光スイッチのようなエンドポイントの電力レベルを制御するには、Alexa.PowerLevelControllerインターフェースを使用します。

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

発話

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

Alexa, dim the bathroom light.
Alexa, set the bedroom light to fifty percent.

アレクサ、浴室の照明を暗くして。
アレクサ、浴室の照明を50パーセント暗くして。

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

プロパティ

brightnessプロパティ

Alexa.BrightnessControllerインターフェースは、brightnessプロパティをプライマリプロパティとして使用します。このプロパティは整数で、有効値は0~100(両端の値を含む)です。brightnessプロパティを使用して変化を表す場合、有効値は-100~100(両端の値を含む)です。

検出

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

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

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

応答例

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

ディレクティブ

SetBrightnessディレクティブ

ユーザーがデバイス設定の輝度値を設定できるように、SetBrightnessディレクティブをサポートします。

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

Alexa, set the table light bulb to fifty percent.

Alexa, mettre le ampoule de cinquante pour cent

Alexa, stelle Glühbirne auf fünfzig prozent

アレクサ、テーブルライトの電球を50パーセントにして。

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

フィールド 説明
percentage デバイスに設定する輝度です。 整数

SetBrightnessディレクティブの例

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

SetBrightness応答イベント

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

SetBrightness応答イベントの例

{
  "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.BrightnessController",
        "name": "brightness",
        "value": 50,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

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

AdjustBrightnessディレクティブ

ユーザーがデバイス設定の輝度値を調節できるように、AdjustBrightnessディレクティブをサポートします。

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

Alexa, dim table light bulb twenty five percent.

Alexa, diminue le ampoule de vingt-cinq pour cent

Alexa, dimme Glühbirne fünfundzwanzig prozent

アレクサ、テーブルライトの電球を25パーセント暗くして。

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

フィールド 説明
brightnessDelta brightnessの変更量です。 整数

AdjustBrightnessディレクティブの例

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

AdjustBrightness応答イベント

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

AdjustBrightness応答イベントの例

{
  "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.BrightnessController",
        "name": "brightness",
        "value": 75,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

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

AdjustBrightnessディレクティブを正しく処理できなかった場合は、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.BrightnessController",
        "name": "brightness",
        "value": 75,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、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.BrightnessController",
            "name": "brightness",
            "value": 75,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {}
}