Alexa.ColorControllerインターフェース



Alexa.ColorControllerインターフェース

AlexaスキルにAlexa.ColorControllerインターフェースを実装すると、色が変化する電球などのデバイスの色をユーザーが変更できるようになります。スマートホームスキルの詳細については、スマートホームスキルAPIについてを参照してください。

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

発話

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

Alexa, set the front porch light to blue.
Alexa, set the bedroom light to red.
Alexa, change the kitchen to the color blue.

Alexa, setze Wohnzimmerlicht auf rosa.

アレクサ、寝室のライトを青にして
アレクサ、キッチンの色をオレンジに変えて

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

プロパティとオブジェクト

colorオブジェクト

colorオブジェクトは、エンドポイントの色を表します。HSBカラーモデル(hue:色相、saturation:彩度、brightness:明度)で色を指定します。詳細については、colorizer.orgThe HSB Color Systemを参照してください。

検出

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

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

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

応答例

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

ディレクティブ

SetColorディレクティブ

SetColorディレクティブをサポートすると、ユーザーがデバイスの色を変更できるようになります。

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

Alexa, set the bedroom light to red.

Alexa, setze Wohnzimmerlicht auf rosa.

アレクサ、寝室のライトを赤に変えて

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

フィールド 説明
color デバイスに設定するです。 オブジェクト

SetColorディレクティブの例

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

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

SetColor応答イベント

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

SetColor応答イベントの例

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

{
  "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.ColorController",
        "name": "color",
        "value": {
            "hue": 350.5,
            "saturation": 0.7138,
            "brightness": 0.6524
        },
        "timeOfSample": "2019-07-03T16:20:50Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

SetColorディレクティブを正しく処理できなかった場合は、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.ColorController",
        "name": "color",
        "value": {
            "hue": 350.5,
            "saturation": 0.7138,
            "brightness": 0.6524
        },
        "timeOfSample": "2019-07-03T16:20:50Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

変更レポート

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

ColorControllerColorTemperatureControllerの両方のインターフェースをサポートする照明エンドポイントでは、エンドポイントに色が設定されたときは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.ColorController",
            "name": "color",
            "value": {
                "hue": 280,
                "saturation": 0.9,
                "brightness": 0.9
            },
            "timeOfSample": "2019-07-03T16:20:50Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {}
}