Alexa.ColorTemperatureControllerインターフェース

Alexa.ColorTemperatureControllerインターフェース

AlexaスキルにAlexa.ColorTemperatureControllerインターフェースを実装すると、白色光の調整が可能なデバイス（電球など）の色温度をユーザーが制御できます。スマートホームスキルの詳細については、スマートホームスキルAPIについてを参照してください。

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

発話

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

Alexa, set the dining room softer.
Alexa, make the living room warmer.
Alexa, set the dining room cooler.
Alexa, make the living room light whiter.
Alexa, make the living room warm white.
Alexa, set the kitchen to daylight.

アレクサ、ダイニングルームをソフトな色にして
アレクサ、リビングを暖かい色にして
アレクサ、ダイニングルームを寒色系にして
アレクサ、リビングの電気をもっと白っぽくして
アレクサ、リビングを暖かい白色にして

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

プロパティ

colorTemperatureInKelvinプロパティ

Alexa.ColorTemperatureControllerインターフェースでは、プライマリプロパティとしてcolorTemperatureInKelvinプロパティを使用します。白色光の調整が可能なエンドポイントで使用されるcolorTemperatureInKelvinプロパティは、エンドポイントの色温度をケルビンで表します。有効な値の範囲は1,000～10,000（両端の値を含む）です。

次の表に色温度値をいくつか示します。ユーザーがリクエストした値をエンドポイントがサポートしていない場合は、最も近い値に設定することをお勧めします。

白の色調 色温度（ケルビン値）
暖色 2200
電球色 2700
白っぽい色 4000
昼白色 5500
クールホワイト 7000

検出

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

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

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

応答例

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

ディレクティブ

SetColorTemperatureディレクティブ

SetColorTemperatureディレクティブをサポートすると、エンドポイントの色温度をユーザーが設定できます。

以下に、ユーザーの発話の例を示します。

Alexa, make the living room warm white.
Alexa, set the kitchen to daylight.

Alexa, schalte Schlafzimmerlicht auf warmes Weiß.

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

フィールド 説明 型
colorTemperatureinKelvin ケルビンで表した色温度です。 整数

SetColorTemperatureディレクティブの例

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


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

SetColorTemperature応答イベント

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

SetColorTemperature応答イベントの例

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

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

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

SetColorTemperatureディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。デバイスが色温度のディレクティブで制御できないモードに設定されている場合、NOT_SUPPORTED_IN_CURRENT_MODEエラータイプを使用します。たとえば、照明がHSBカラーに設定されている場合は、エラーを返し、Alexaに「それは照明の色調が白に設定されているときだけ可能です」と応答させます。

IncreaseColorTemperatureディレクティブ

IncreaseColorTemperatureディレクティブをサポートすると、ユーザーがエンドポイントの色温度を上げることができます。このディレクティブは特定の値を指定しませんが、デバイスの現在の設定よりも寒色または白色寄りの設定をリクエストします。デバイスの設定をどの程度調整するかを選択できます。それ以上設定を上げることができない場合、最大の色温度にデバイスを設定します。

以下に、ユーザーの発話の例を示します。

Alexa, set the dining room cooler.
Alexa, make the living room light whiter.

IncreaseColorTemperatureディレクティブの例

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

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

IncreaseColorTemperature応答イベント

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

IncreaseColorTemperature応答イベントの例

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

{
  "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.ColorTemperatureController",
        "name": "colorTemperatureInKelvin",
        "value": 7000,
        "timeOfSample": "2018-02-05T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

IncreaseColorTemperatureディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。デバイスが色温度のディレクティブで制御できないモードに設定されている場合、NOT_SUPPORTED_IN_CURRENT_MODEエラータイプを使用します。たとえば、照明がHSBカラーに設定されている場合は、エラーを返し、Alexaに「それは照明の色調が白に設定されているときだけ可能です」と応答させます。

DecreaseColorTemperatureディレクティブ

DecreaseColorTemperatureディレクティブをサポートすると、ユーザーがエンドポイントの色温度を下げることができます。このディレクティブは特定の値を指定しませんが、デバイスの現在の設定よりも暖色または柔らかい色の設定をリクエストします。デバイスの設定をどの程度調整するかを選択できます。それ以上設定を下げることができない場合、最小の色温度にデバイスを設定します。

以下に、ユーザーの発話の例を示します。

Alexa, set the dining room softer.
Alexa, make the living room warmer.

DecreaseColorTemperatureディレクティブの例

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

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

DecreaseColorTemperature応答イベント

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

DecreaseColorTemperature応答イベントの例

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

{
  "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.ColorTemperatureController",
        "name": "colorTemperatureInKelvin",
        "value": 2200,
        "timeOfSample": "2019-02-05T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

DecreaseColorTemperatureディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。デバイスが色温度のディレクティブで制御できないモードに設定されている場合、NOT_SUPPORTED_IN_CURRENT_MODEエラータイプを使用します。たとえば、照明がHSBカラーに設定されている場合は、エラーを返し、Alexaに「それは照明の色調が白に設定されているときだけ可能です」と応答させます。

状態レポート

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.ColorTemperatureController",
        "name": "colorTemperatureInKelvin",
        "value": 2200,
        "timeOfSample": "2019-02-05T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

変更レポート

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

ColorControllerとColorTemperatureControllerの両方のインターフェースをサポートする照明エンドポイントでは、エンドポイントに色が設定されたときはcolorの状態を、エンドポイントに白の色調が設定されたときはcolorTemperatureInKelvinの状態をレポートします。

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.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 4000,
            "timeOfSample": "2019-02-05T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {}
}
このページは役に立ちましたか？

最終更新日: 2020 年 12 月 22 日