Alexa.PercentageControllerインターフェース

Alexa.PercentageControllerインターフェース

Alexa.PercentageControllerインターフェースは、パーセンテージで表現できるエンドポイントのプロパティを制御するためのメッセージを記述します。

このインターフェースは、デバイスに適用される固有のコントローラーインターフェースが存在しない場合にのみ使用します。たとえば、輝度値に固有のリクエストを処理する場合は、代わりにAlexa.BrightnessControllerインターフェースを実装します。調光スイッチのようなエンドポイントの電力レベルに固有のリクエストを処理するには、Alexa.PowerLevelControllerインターフェースを実装します。

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

発話

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

Alexa, set the <device name> to thirty percent.
Alexa, increase <device name> by ten percent.
Alexa, decrease <device name> by twenty percent.

Alexa, stelle <Geräteame> auf Anzahl Prozent.
Alexa, erhöhe <Gerätename> um 10 Prozent.
Alexa, reduziere <Gerätename> um 20 Prozent.

＜デバイス名＞を30%に設定して。
アレクサ、＜デバイス名＞を10パーセント上げて。
アレクサ、＜デバイス名＞を20パーセント下げて。

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

プロパティ

percentageプロパティ

Alexa.PercentageControllerインターフェースは、percentageプロパティをプライマリプロパティとして使用します。このプロパティは整数で、有効値は0～100（両端の値を含む）です。percentageプロパティを使用して変化を表す場合、有効値は-100～100（両端の値を含む）です。

検出

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

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

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

応答例

以下は、Alexa.PercentageControllerインターフェースをサポートする1つのエンドポイントへの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": ["OTHER"],
                    "cookie": {},
                    "capabilities": [
                        {
                            "type": "AlexaInterface",
                            "interface": "Alexa.PercentageController",
                            "version": "3",
                            "properties": {
                                "supported": [
                                    {
                                        "name": "percentage"
                                    }
                                ],
                                "proactivelyReported": true,
                                "retrievable": true
                            }
                        }
                    ]
                }
            ]
        }
    }
}

ディレクティブ

SetPercentageディレクティブ

ユーザーがデバイス設定のパーセント値を設定できるように、SetPercentageディレクティブをサポートします。

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

Alexa, set the <device name> to thirty percent.

Alexa, stelle <Geräteame> auf Anzahl Prozent.

＜デバイス名＞を30%に設定して。

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

フィールド 説明 型
percentage デバイスに設定するパーセント値です。 整数

SetPercentageディレクティブの例

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

SetPercentage応答イベント

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

SetPercentage応答イベントの例

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

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

SetPercentageディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

AdjustPercentageディレクティブ

ユーザーがデバイス設定のパーセント値を調整できるように、AdjustPercentageディレクティブをサポートします。

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

Alexa, increase <device name> by ten percent.
Alexa, decrease <device name> by twenty percent.

Alexa, erhöhe <Gerätename> um 10 Prozent.
Alexa, reduziere <Gerätename> um 20 Prozent.

アレクサ、＜デバイス名＞を10パーセント上げて。
アレクサ、＜デバイス名＞を20パーセント下げて。

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

フィールド 説明 型
percentageDelta パーセント値の変更量です。 整数

AdjustPercentageディレクティブの例

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

AdjustPercentage応答イベント

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

AdjustPercentage応答イベントの例

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

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

AdjustPercentageディレクティブを正しく処理できなかった場合は、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.PercentageController",
           "name": "percentage",
           "value": 30,
           "timeOfSample": "2017-02-03T16:20:50.52Z",
           "uncertaintyInMilliseconds": 0
       }
      ]
    }
}

変更レポート

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