Alexa.ToggleControllerインターフェース

Alexa.ToggleControllerインターフェース

Alexa.ToggleController機能インターフェースは、エンドポイントの設定を切り替えるために使用するメッセージを記述します。ToggleControllerインターフェースを使用すると、扇風機の首振り機能やオーブンの庫内灯など、オンまたはオフに設定できるエンドポイントプロパティをモデル化できます。また、ToggleControllerインターフェースでは、ユーザーが変更できないエンドポイントプロパティもモデル化できます。

ToggleControllerインターフェースは設定の柔軟性がきわめて高く、各種デバイス用にさまざまな設定をモデル化できます。以下の具体的なインターフェースの中にデバイスに適したものがある場合は、そちらを使用してください。

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

発話

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

アレクサ、コーヒーメーカーをつけて
アレクサ、エコモードを消して
アレクサ、扇風機の首振りはついている？
アレクサ、オーブンの電気を消して

Alexa, turn on the ice maker.
Alexa, turn off eco mode.
Alexa, is oscillate on for the tower fan?

オプションで、セマンティクスを使用して発話を追加できます。以下に、追加できるユーザーの発話の例を示します。

アレクサ、ゴミ箱のフタを開いて
アレクサ、ゴミ箱のフタを閉じて

Alexa, open the garbage can lid.
Alexa, close the garbage can lid.

Alexa, öffne der Deckel der Mülltonne.
Alexa, schließe der Deckel der Mülltonne.

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

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

toggleStateプロパティ

Alexa.ToggleControllerインターフェースは、toggleStateプロパティをプライマリプロパティとして使用します。有効な値はONまたはOFFです。

1つのエンドポイントで複数のトグルをサポートできるため、toggleStateプロパティにはinstanceアトリビュートを必ず含めてください。instance名は検出応答で指定します。

ToggleStateプロパティの例

{
  "namespace": "Alexa.ToggleController",
  "instance": "Oven.OvenLight",
  "name": "toggleState",
  "value": "ON"
}

セマンティクスを使用して発話を追加する

Alexa.ToggleControllerインターフェースを使用する場合、音声対話モデルは既にビルドされています。ユーザーは、デバイスとの対話にToggleController標準の発話を使用できます。詳細については、発話を参照してください。

オプションで、セマンティクスを使用して発話を追加できます。セマンティクスを使用する場合は、「開いて」、「閉じて」、「上げて」、「下げて」といったフレーズを、ToggleControllerのディレクティブであるTurnOnとTurnOffに手動でマップします。たとえば、ごみ箱のふた用のコントローラーでは、「開けて」をTurnOnディレクティブにマップできます。

セマンティクスは同じデバイスの複数のコントローラーでサポートできますが、各コントローラーで異なるフレーズをサポートすることが必要となります。たとえば、「開いて」をToggleControllerでサポートし、「上げて」をRangeControllerでサポートすることはできますが、「開いて」をToggleControllerとRangeControllerの両方でサポートすることはできません。

セマンティクスを使用するには、次のセクションで説明するように、検出応答にsemanticsオブジェクトを含めます。

検出

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

Alexaからの状態レポートリクエストに応じてスキルがレポートする場合は、プロパティのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートする場合はプロパティのproactivelyReportedをtrueに設定します。

ユーザーが変更できないエンドポイントプロパティは、nonControllableをtrueに設定することでモデル化できます。たとえば、コンロに余熱があり上面が熱くて触れられないことをユーザーに警告する安全機能が付いている場合は、ユーザーによる変更を許可せずにその状態をレポートできます。

機能配列の各ToggleControllerエントリには、オプションでsemanticsオブジェクトを含めることができます。詳細については、セマンティクスを使用して発話を追加するを参照してください。

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

機能配列の各ToggleControllerエントリには、通常の検出応答フィールドのほかに、次のフィールドを含めます。

フィールド 説明 型
instance トグルの名前です。例：Fan.Light、Fan.Oscillate 文字列
capabilityResources ユーザーがトグルのリクエストに使用できるフレンドリー名です。 CapabilityResourcesオブジェクト

検出応答の例

検出応答の例

以下は、Alexa.ToggleControllerインターフェースをサポートする1つのエンドポイントへのDiscover.Responseメッセージの例です。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "Kitchen Appliance Plus",
          "description": "Kitchen Appliance Plus製スマートオーブン",
          "friendlyName": "オーブン",
          "displayCategories": ["OTHER"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Oven.OvenLight",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true,
                "nonControllable": false
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "オーブンライト",
                      "locale": "ja-JP"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "Stovetop.ResidualHeat",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true,
                "nonControllable": true
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "コンロの上面はまだ熱くなっています",
                      "locale": "ja-JP"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

セマンティクスを使用した検出応答の例

以下は、Alexa.ToggleControllerインターフェースをサポートする1つの自動開閉式ごみ箱へのDiscover.Responseメッセージの例です。この例ではセマンティクスを使用しています。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<メーカー名>",
          "description": "<メーカー製スマートごみ箱>",
          "friendlyName": "<ごみ箱>",
          "displayCategories": ["OTHER"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "instance": "GarbageCan.Lid",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "ごみ箱のふた",
                      "locale": "ja-JP"
                    }
                  }
                ]
              },
              "semantics": {
                "actionMappings": [
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Close"],
                    "directive": {
                      "name": "TurnOff",
                      "payload": {}
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Open"],
                    "directive": {
                      "name": "TurnOn",
                      "payload": {}
                    }
                  }
                ],
                "stateMappings": [
                  {
                    "@type": "StatesToValue",
                    "states": ["Alexa.States.Closed"],
                    "value": "OFF"
                  },
                  {
                    "@type": "StatesToValue",
                    "states": ["Alexa.States.Open"],
                    "value": "ON"
                  }  
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

TurnOnディレクティブ

TurnOnディレクティブをサポートすると、ユーザーがデバイスをオンにできます。

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

アレクサ、オーブンの電気をつけて

Alexa, turn on light on the oven.

TurnOnディレクティブの例

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

TurnOn応答イベント

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

TurnOn応答イベントの例

{
  "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.ToggleController",
        "instance": "Oven.Light",
        "name": "toggleState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

TurnOnディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。安全性に関わるエラーの場合は、Alexa.Safety.ErrorResponseを使用して応答します。

TurnOffディレクティブ

TurnOffディレクティブをサポートすると、ユーザーがデバイスをオフにできます。

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

アレクサ、オーブンの電気を消して

Alexa, turn off light on the oven.

TurnOffディレクティブの例

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

TurnOff応答イベント

TurnOffディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、変更されたすべてのプロパティの値を含めます。

TurnOff応答イベントの例

{
  "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.ToggleController",
        "instance": "Oven.Light",
        "name": "toggleState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

TurnOffディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。安全性に関わるエラーの場合は、Alexa.Safety.ErrorResponseを使用して応答します。

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするためにReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態レポートについてを参照してください。

ReportStateディレクティブをサポートすると、ユーザーがデバイスの機能がオンかオフかを質問できます。

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

Alexa, is residual heat on for the oven?

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.ToggleController",
        "instance": "Stovetop.ResidualHeat",
        "name": "toggleState",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ToggleController",
        "instance": "Oven.Light",
        "name": "toggleState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、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.ToggleController",
            "instance": "Oven.OvenLight",
            "name": "toggleState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ToggleController",
            "instance": "Stovetop.ResidualHeat",
            "name": "toggleState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {}
}
このページは役に立ちましたか？