Alexa.ModeControllerインターフェース 3
ユーザーがデバイスのモード設定を制御できるように、AlexaスキルにAlexa.ModeController
インターフェースを実装しましょう。Alexa.ModeController
インターフェースを使用すると、洗濯乾燥機の洗浄サイクルモードなど、ユーザーがリストのいずれかの値に設定できるデバイスのプロパティをモデル化できます。値のリストには順序を設定できますが、必須ではありません。Alexa.ModeController
インターフェースは汎用コントローラーインターフェースです。
Alexa.ModeController
インターフェースは設定の柔軟性がきわめて高く、各種デバイス用にさまざまな設定をモデル化できます。以下の具体的なインターフェースの中にデバイスに適したものがある場合は、そちらを使用してください。
- Alexa.CookingとCookingMode
- Alexa.EqualizerControllerとMode
- Alexa.LockControllerとLockState
- Alexa.ThermostatControllerとThermostatMode
Alexa.ModeController
インターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。
de-DE
、en-GB
、en-US
、es-ES
、fr-FR
、it-IT
でサポートされています。メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。
発話
Alexa.ModeController
インターフェースではプリビルド音声対話モデルを使用します。以下に、ユーザーの発話の例を示します。
Alexa, what's the wash setting on the washer?
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
Alexa, increase the water temperature on the washer.
アレクサ、扇風機は何に設定されている?
アレクサ、洗濯機をデリケートモードにして
アレクサ、洗濯モードをドライに設定して
アレクサ、洗濯機の水位を上げて
セマンティクスを使用すると、発話を追加できます。以下は、セマンティクスを使用して有効にしたユーザーの発話の例です。
Alexa, open the garage door.
Alexa, close the garage door.
Alexa, raise the bedroom blinds.
Alexa, lower the living room blinds.
Alexa, fahre das Rollo in der Küche hoch.
Alexa, fahre das Küchenrollo hoch.
Alexa, fahr das Wohnzimmer-Rollo runter.
Alexa, fahre die Rollläden im Wohnzimmer runter.
アレクサ、ゴミ箱のふたを開けて
アレクサ、ブラインドを閉めて
アレクサ、シェードを上げて
アレクサ、プロジェクタースクリーンを下げて
ユーザーがこのような発話をすると、Alexaはそれに対応するディレクティブをスキルに送信します。
プロパティとオブジェクト
Modeプロパティ
Alexa.ModeController
インターフェースでは、プライマリプロパティとしてmode
プロパティを使用します。プロパティ値は文字列です。Mode
オブジェクトは、そのモードで許容される値を定義します。
エンドポイントは複数のモードに対応しています。モードを区別するために、常にinstance
アトリビュートを含める必要があります。このアトリビュートはモードの名前を定義します。instance
名は検出応答で識別します。
Modeプロパティの例
{
"namespace": "Alexa.ModeController",
"name": "mode",
"instance": "Washer.WashTemperature",
"value": "WashTemperature.Cold"
}
Modeオブジェクト
Mode
オブジェクトには、モードで許容される値を指定します。検出応答で、supportedModes
配列に少なくとも2つのMode
オブジェクトを含めます。
以下は、2つのMode
オブジェクトを含むsupportedModes
配列の例です。
"supportedModes": [
{
"value": "WashCycle.Normal",
"modeResources": {
}
},
{
"value": "WashCycle.Delicates",
"modeResources": {
}
}
]
以下の表は、Mode
オブジェクトのプロパティを示しています。
フィールド | 説明 | 型 |
---|---|---|
value |
モード値の名前です。 | String |
modeResources |
ユーザーがモードの操作に使用できるフレンドリー名です。 | ModeResourcesオブジェクト |
ModeResourcesオブジェクト
ModeResources
オブジェクトを使用して、ユーザーがモード値の操作に使用できる一連のフレンドリー名を指定します。最初のフレンドリー名が、Alexaアプリに表示される名前です。詳細については、リソースとアセットを参照してください。
以下は、洗濯機のデリケート洗浄サイクルに使用するモードリソースの例です。ユーザーは、「アレクサ、洗浄サイクルをニットに設定して」などのフレーズを使用できます。
"modeResources":
{
"friendlyNames": [
{
"@type": "asset",
"value": {
"assetId": "Alexa.Value.Delicate"
}
},
{
"@type": "text",
"value": {
"text": "デリケート",
"locale": "ja-JP"
}
},
{
"@type": "text",
"value": {
"text": "ニット",
"locale": "ja-JP"
}
},
{
"@type": "text",
"value": {
"text": "Ciclo delicado",
"locale": "es-MX"
}
},
{
"@type": "text",
"value": {
"text": "Cycle délicat",
"locale": "fr-CA"
}
}
]
}
セマンティクス
セマンティクスを使用すると、ユーザー発話の追加やデバイスに注意を向けてもらう必要がある場合の通知など、追加の機能を有効にすることができます。セマンティクスを使用するには、検出のセクションで説明するように、検出応答にsemanticsオブジェクトを含めます。
セマンティクスを使用して発話を追加する
Alexa.ModeController
インターフェースを使用する場合、音声対話モデルは既にビルドされています。ユーザーは、デバイスとの対話にAlexa.ModeController
の標準の発話を使用できます。詳細については、発話を参照してください。
オプションで、セマンティクスを使用して発話を追加できます。セマンティクスを使用する場合は、「開いて」、「閉じて」、「上げて」、「下げて」といったフレーズを、Alexa.ModeController
のディレクティブであるSetModeとAdjustModeに手動でマップします。たとえば、ガレージドアオープナーの場合、「開けて」をSetMode
ディレクティブにマップできます。
開いて
というフレーズをAlexa.ModeController
インスタンスにマップする場合、開いて
というフレーズをその他のAlexa.ModeController
インスタンス、Alexa.RangeController
インスタンス、Alexa.ToggleController
インスタンスにはマップできません。セマンティクスを使用して通知を有効にする
セマンティクスを使用して、デバイスに注意を向けてもらう必要がある場合にユーザーに通知することができます。通知の形式は、<デバイスのフレンドリー名>が<状態>
となります。たとえば、自動運転掃除機に何かが詰まった場合、Alexaは次のようにユーザーに通知します: 「掃除機が詰まっています」
通知を有効にするには、AlexaスキルにAlexa.ProactiveNotificationSource
インターフェースを実装します。サポートする状態を指定するには、検出応答にsemanticsオブジェクトを含め、mode
プロパティをAlexa.States.Stuck
などのAlexa.States
値のいずれかにマップします。通知をトリガーするには、デバイスの状態の変更をレポートするAlexa.ChangeReport
を送信します。詳細については、Alexa.ProactiveNotificationSourceインターフェースを参照してください。
検出
Alexa.ModeController
をサポートするエンドポイントを指定するには、Alexa.Discoveryの標準検出メカニズムを使用します。
Alexaからスキルに状態レポートリクエストが送信されたら、レポートするプロパティのretrievable
をtrueに設定します。変更レポートでAlexaにプロアクティブにレポートする場合はプロパティのproactivelyReported
をtrueに設定します。
Alexa user identificationを使用するConnected Vehicleの場合は、検出レスポンスにdirectiveConfigurations
を含めて、認証の信頼レベルとポリシー名を設定します。詳細については、directiveConfigurationsを参照してください。
ユーザーが変更できないエンドポイントのプロパティは、nonControllable
をtrueに設定することでモデル化できます。たとえば、洗濯機が自動で洗い、すすぎ、脱水に移行する場合、洗浄サイクルの変更を許可せずに、現在の洗浄サイクルをユーザーにレポートできます。
capabilities
配列の各Alexa.ModeController
エントリに、オプションでsemanticsオブジェクトを含めることができます。詳細については、セマンティクスを使用して発話を追加するおよびセマンティクスを使用して通知を有効にするを参照してください。
表示カテゴリーの一覧は、表示カテゴリーを参照してください。
capabilities配列
capabilities
配列の各Alexa.ModeController
エントリには、通常の検出応答フィールドのほかに、次のフィールドを含めます。
フィールド | 説明 | 型 |
---|---|---|
instance |
Washer.WashCycle やWasher.WashTemperature といったモード名です。 |
String |
capabilityResources |
ユーザーがモードとの対話に使用できるフレンドリー名です。 インスタンスのフレンドリー名の通知を有効にする場合は、 @type を含めてtext に設定します。 |
CapabilityResourcesオブジェクト |
configuration.ordered |
モード名が順序付けされている場合はtrue に設定し、それ以外の場合はfalse に設定します。たとえば、洗浄温度モードは、低温、中温、高温の順に並べることができます。 順序付けされているモードは AdjustMode ディレクティブをサポートします。 |
Boolean |
configuration. supportedModes |
受け入れられるモード値のリストを指定します。 2つ以上のモードオブジェクトを含める必要があります。 順序付けされたモード値を配列に昇順で列挙します。 |
Modeオブジェクトの配列 |
検出応答の例
洗濯乾燥機の例
以下は、次の3つのインスタンスで定義される3つのモードをサポートする洗濯乾燥機に対するDiscover.Response
メッセージの例です: Washer.WashCycle
、Washer.CurrentWashCycle
、Washer.WashTemperature
。
ブラインドのセマンティクスの例
以下は、Alexa.ModeController
インターフェースをサポートするブラインドに対するDiscover.Response
メッセージの例です。この例ではセマンティクスを使用しています。ブラインドで対応できるのが全開と全閉だけの場合は、Alexa.ModeController
インターフェースを使用します。範囲内の位置で上げ下げができるブラインドの場合は、代わりにRangeControllerインターフェースを使用します。
Alexa.ModeController
インターフェースは、次のロケールでブラインドを制御するスキルに使用できます:de-DE
、en-AU
、en-GB
、en-IN
、en-US
、es-ES
、es-MX
、es-US
、it-IT
、ja-JP
。
ガレージドアオープナーのセマンティクスの例
以下は、Alexa.ModeController
インターフェースをサポートするガレージドアオープナーに対するDiscover.Response
メッセージの例です。この例ではセマンティクスを使用しています。デバイスがガレージドアオープナーの場合、Alexa.ModeController
インターフェースとGARAGE_DOOR
表示カテゴリーの両方を使う必要があります。
ガレージドアデバイスの場合、ユーザーがガレージドアを開けるよう言うと、Alexaはガレージドアを開ける前に「確認コードは何ですか?」とたずねます。
Alexa.ModeController
インターフェースは、次のロケールでガレージドアを制御するスキルに使用できます:de-DE
, en-GB
, en-US
, es-ES
, fr-FR
, it-IT
。
ディレクティブ
Alexaは次のAlexa.ModeController
インターフェースディレクティブをスキルに送信します。
SetModeディレクティブ
SetMode
ディレクティブをサポートすると、ユーザーがデバイスのモードを設定できます。
以下は、ユーザーの発話の例です。
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
アレクサ、洗濯機をデリケートモードにして
アレクサ、洗濯モードをドライに設定して
SetModeディレクティブの例
以下は、Alexaがスキルに送信するSetMode
ディレクティブの例です。
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"instance": "Washer.WashCycle",
"name": "SetMode",
"messageId": "一意のバージョン4 UUID",
"correlationToken": "opaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0ベアラートークン"
},
"endpointId": "エンドポイントID",
"cookie": {}
},
"payload": {
"mode": "WashCycle.Normal"
}
}
}
SetModeディレクティブペイロード
プロパティ | 説明 | 型 | 必須 |
---|---|---|---|
|
デバイスに設定するモードです。 |
String |
◯ |
SetMode応答
SetMode
ディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。
contextオブジェクトに、変更されたすべてのプロパティの値を含めます。レポートするmodeプロパティごとに、instance
アトリビュートを含める必要があります。
次の例は、Washer.WashCycle
モードの値が変更されたことをレポートしています。
{
"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.ModeController",
"instance": "Washer.WashCycle",
"name": "mode",
"value": "WashCycle.Normal",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
SetModeディレクティブのエラー処理
SetMode
ディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。安全性に関わるエラーの場合は、Alexa.Safety.ErrorResponseを使用して応答します。
AdjustModeディレクティブ
順序付けされているモードの場合は、AdjustMode
ディレクティブをサポートし、ユーザーがデバイスのモードを調整できるようにします。
このディレクティブの検出応答でconfiguration.ordered
をtrue
に設定すると、ユーザーは指定された差分だけモードを増減できます。このディレクティブは、現在のモードによってリクエストを限定することはありません。増減リクエストを適切に処理することで、複数のモード間を遷移することができます。
以下は、ユーザーの発話の例です。
Alexa, increase the water temperature on the washer.
アレクサ、洗濯機の水温を上げて
AdjustModeディレクティブの例
以下の例は、Alexaがスキルに送信するAdjustMode
ディレクティブを示しています。
{
"directive": {
"header": {
"namespace": "Alexa.ModeController",
"instance": "Washer.WashTemperature",
"name": "AdjustMode",
"messageId": "一意のバージョン4 UUID",
"correlationToken": "opaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0ベアラートークン"
},
"endpointId": "エンドポイントID",
"cookie": {}
},
"payload": {
"modeDelta": 1
}
}
}
AdjustModeディレクティブペイロード
プロパティ | 説明 | 型 | 必須 |
---|---|---|---|
|
モードの変更量です。デフォルトは1です。 |
Integer |
✕ |
AdjustMode応答
AdjustMode
ディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。
contextオブジェクトに、変更されたすべてのプロパティの値を含めます。レポートするmodeプロパティごとに、instance
アトリビュートを含める必要があります。
以下は、AdjustMode
応答の例です。
{
"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.ModeController",
"instance": "Washer.WashTemperature",
"name": "mode",
"value": "WashTemperature.Warm",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
AdjustModeディレクティブのエラー処理
AdjustMode
ディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。安全性に関わるエラーの場合は、Alexa.Safety.ErrorResponseを使用して応答します。
状態レポート
Alexaはエンドポイントの状態についての情報をリクエストするために、ReportState
ディレクティブを送信します。AlexaがReportState
ディレクティブを送信したら、それに対する応答としてStateReport
イベントを送信します。状態レポートの詳細については、状態および変更レポートについてを参照してください。
この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態が含まれます。レポートするmodeプロパティごとに、instance
アトリビュートを含める必要があります。検出応答で、状態が照会可能なプロパティとinstance
名を識別します。
デバイスの電源がオフになっているなど、モードがセットされていない場合、mode
プロパティをnull
としてレポートします。
ReportState
ディレクティブをサポートすると、ユーザーがデバイスの機能について質問できます。
以下に、ユーザーの発話の例を示します。
Alexa, what's the current washer cycle?
アレクサ、洗濯機のモードは何にセットされている?
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.ModeController",
"instance": "Washer.WashCycle",
"name": "mode",
"value": "WashCycle.Delicates",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
変更レポート
エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReport
イベントを送信します。変更レポートの詳細については、状態および変更レポートについてを参照してください。
ChangeReport
には、ペイロードオブジェクトで変更されたすべてのプロパティ値が含まれます。レポートするmode
プロパティごとにinstance
アトリビュートを含める必要があります。検出応答で、プロアクティブにレポートするプロパティとinstance
名を識別します。
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.ModeController",
"instance": "Washer.WashTemperature",
"name": "mode",
"value": "WashTemperature.Hot",
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50Z",
"uncertaintyInMilliseconds": 0
}
}
関連トピック
最終更新日: 2022 年 11 月 08 日