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

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

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

ColorControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

発話

Alexa.ColorControllerインターフェースを使用する場合、音声対話モデルは既にビルドされています。ユーザーが次のいずれかの発話をしたら、Alexaがそれに対応するディレクティブをスキルに送信します。

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

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

Alexa, schalte das Wohnzimmerlicht hellblau.

Alexa, règle la lumière du vestibule en bleu.
Alexa, mets la cuisine en bleu.

Alexa, फ्रंट पोर्च लाइट को ब्लू पर सेट करें।
Alexa, किचन को नीले रंग में बदलें।

Alexa, imposta la luce del portico anteriore su blu.
Alexa, cambia la cucina con il colore blu.

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

Alexa, coloque a luz da entrada em azul.
Alexa, mude luz da entrada para azul.
Alexa, coloque a luz da cozinha em vermelho.
Alexa, mude luz da cozinha para vermelho.

Alexa, pon la luz del porche delantero en azul.
Alexa, cambia la cocina al color azul.

Alexa, zet het licht op de veranda op blauw.
Alexa, verander de keuken naar de kleur blauw.

出力可能なプロパティ

colorオブジェクトは、エンドポイントの色を表します。HSBカラーモデル（hue：色相、saturation：彩度、brightness：明度）で色を指定します。詳細については、colorizer.orgとHSBカラー体系（英語）を参照してください。

検出

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

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

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

Alexaにデバイスの健全性を通知する場合、Alexa.EndpointHealthインターフェースも実装してください。

検出応答の例

以下は、Alexa.PowerControllerインターフェースと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" : "デバイスのモデル",
            "customIdentifier": "デバイスの任意のカスタム識別子"
          },
          "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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

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

SetColorディレクティブ

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

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

Alexa, set the bedroom light to red.

Alexa, schalte das Wohnzimmerlicht rot.

Alexa, règle la lumière de la chambre en rouge.

Alexa, बेडरूम की लाइट को लाल रंग में सेट करो।

Alexa, imposta la luce della camera da letto sul rosso.

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

Alexa, coloque a luz do quarto em vermelho.
Alexa, mude luz do quarto para vermelho.

Alexa, pon la luz del dormitorio en rojo.

Alexa, zet de slaapkamerlamp op rood.

SetColorディレクティブの例

以下は、Alexaがスキルに送信するSetColorディレクティブの例です。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ColorController",
      "name": "SetColor",
      "messageId": "一意のバージョン4 UUID",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "color": {
        "hue": 350.5,
        "saturation": 0.7138,
        "brightness": 0.6524
      }
    }
  }
}

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

次の表は、SetColorディレクティブのペイロードの詳細を示しています。

プロパティ 説明 型 必須

color

デバイスに設定する色です。

オブジェクト

◯

SetColor応答

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

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

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

{
  "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.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": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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イベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

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

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.ColorController",
            "name": "color",
            "value": {
                "hue": 280,
                "saturation": 0.9,
                "brightness": 0.9
            },
            "timeOfSample": "2024-02-03T16:17:00.00Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2024-02-03T16:15:00.00Z",
    "uncertaintyInMilliseconds": 0
  }
}

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

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