Alexa.RangeControllerインターフェース

Note: Sign in to the developer console to build or publish your skill.

Alexa.RangeController機能インターフェースは、最大値と最小値の範囲内の数値で表されるエンドポイントの設定を制御するために使用するメッセージを記述します。RangeControllerインターフェースを使用すると、ミキサーや扇風機のスピード設定など、範囲内のいずれかの値に設定できるエンドポイントプロパティをモデル化できます。また、RangeControllerインターフェースでは、ユーザーが変更できないエンドポイントプロパティもモデル化することができます。

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

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

発話
プロパティとオブジェクト
- rangeValueプロパティ
セマンティクスを使用して発話を追加する
検出
検出応答の例
- 検出応答の例
- ブラインドの検出応答の例
ディレクティブ
- SetRangeValueディレクティブ
- AdjustRangeValueディレクティブ
状態レポート
変更レポート
関連トピック

発話

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

日本語
英語（すべて）

アレクサ、扇風機の風量を7にして
アレクサ、扇風機の風量を最大にして
アレクサ、扇風機の風量を上げて
アレクサ、扇風機の風量を3弱めて
アレクサ、扇風機の風量は？

Alexa, set the bedroom fan speed to 7.
Alexa, set the fan speed on the bedroom fan to maximum.
Alexa, turn up the bedroom fan speed.
Alexa, decrease the fan speed on the bedroom fan by 3.
Alexa, what is the bedroom fan speed?

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

アレクサ、ブラインドを上げて
アレクサ、ブラインドを下げて
アレクサ、カーテンを開いて
アレクサ、カーテンを閉じて

Alexa, raise the living room blinds.
Alexa, lower the living room blinds.
Alexa, open the bedroom blinds.
Alexa, close the bedroom blinds.

Alexa, fahre die Rollläden im Wohnzimmer hoch.
Alexa, fahre die Rollläden im Wohnzimmer runter.
Alexa, öffne das Rollo in der Küche.
Alexa, schließe das Rollo in der Küche.

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

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

rangeValueプロパティ

Alexa.RangeControllerインターフェースでは、プライマリプロパティとしてrangeValueプロパティを使用します。プロパティ値は数値で、最小値、最大値、精度を検出応答で指定します。rangeValueプロパティを使用して範囲を表す場合は、有効値として負の値を含めることができます。

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

rangeValueプロパティの例

{
  "namespace": "Alexa.RangeController",
  "instance": "Fan.Speed",
  "name": "rangeValue",
  "value": "10"
}

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

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

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

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

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

検出

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

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

ユーザーが変更できないエンドポイントプロパティは、nonControllableをtrueに設定することでモデル化できます。ユーザーに対してレポートは行う一方で変更は許可しない範囲コントローラープロパティについては、nonControllableをtrueに設定します。

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

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

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

フィールド	説明	型
`instance`	範囲の名前です。例：`Fan.Speed`	文字列
`capabilityResources`	ユーザーがモードとの対話に使用できるフレンドリー名です。	CapabilityResourcesオブジェクト
`configuration.` `supportedRange.` `minimumValue`	範囲の最小値です。	数値
`configuration.` `supportedRange.` `maximumValue`	範囲の最大値です。	数値
`configuration.` `supportedRange.` `precision`	範囲内で遷移する場合の値の変化量です。この値は、ユーザーが値の変更を要求したものの分量を指定しなかった場合のデフォルトとしても用いられます。	数値
`unitOfMeasure`	範囲の単位です。	単位を表す文字列
`presets`	ユーザーが数値以外に指定できる名前付きオプションです。例：「medium」、「maximum」	オブジェクトの配列
`preset.` `rangeValue`	プリセットの値です。	数値
`preset.` `presetResources`	ユーザーがプリセット値をリクエストするために使用できるフレンドリー名です。	CapabilityResourcesオブジェクト

検出応答の例

以下は、Alexa.RangeControllerインターフェースとAlexa.PowerControllerインターフェースをサポートする1つの扇風機を表すDiscover.Responseメッセージの例です。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "<Alexaアプリに表示されているデバイス名>",
          "displayCategories": ["FAN"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "instance": "Fan.Speed",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true,
                "nonControllable": false
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "asset",
                    "value": {
                      "assetId": "Alexa.Setting.FanSpeed"
                    }
                  }
                ]
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": 1,
                  "maximumValue": 10,
                  "precision": 1
                },
                "presets": [
                  {
                    "rangeValue": 10,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "asset",
                          "value": {
                            "assetId": "Alexa.Value.Maximum"
                          }
                        },
                        {
                          "@type": "asset",
                          "value": {
                            "assetId": "Alexa.Value.High"
                          }
                        },
                        {
                          "@type": "text",
                          "value": {
                            "text": "最大",
                            "locale": "ja-JP"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ブラインドの検出応答の例

以下は、Alexa.RangeControllerインターフェースをサポートするブラインドに対するDiscover.Responseメッセージの例です。この例ではセマンティクスを使用しています。範囲内の位置で上げ下げができるブラインド用のRangeControllerインターフェースを使用していますが、ブラインドで対応できるのが全開と全閉だけの場合は、代わりにModeControllerインターフェースを使用します。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "<Alexaアプリに表示されているデバイス名>",
          "displayCategories": ["INTERIOR_BLIND"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "instance": "Blind.Lift",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "asset",
                    "value": {
                      "assetId": "Alexa.Setting.Opening"
                    }
                  }
                ]
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": 0,
                  "maximumValue": 100,
                  "precision": 1
                },
                "unitOfMeasure": "Alexa.Unit.Percent"
              },
              "semantics": {
                "actionMappings": [
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Close"],
                    "directive": {
                      "name": "SetRangeValue",
                      "payload": {
                        "rangeValue": 0
                      }
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Open"],
                    "directive": {
                      "name": "SetRangeValue",
                      "payload": {
                        "rangeValue": 100
                      }
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Lower"],
                    "directive": {
                      "name": "AdjustRangeValue",
                      "payload": {
                        "rangeValueDelta" : -10,
                        "rangeValueDeltaDefault" : false
                      }
                    }
                  },
                  {
                    "@type": "ActionsToDirective",
                    "actions": ["Alexa.Actions.Raise"],
                    "directive": {
                      "name": "AdjustRangeValue",
                      "payload": {
                        "rangeValueDelta" : 10,
                        "rangeValueDeltaDefault" : false
                      }
                    }
                  }
                ],
                "stateMappings": [
                  {
                    "@type": "StatesToValue",
                    "states": ["Alexa.States.Closed"],
                    "value": 0
                  },
                  {
                    "@type": "StatesToRange",
                    "states": ["Alexa.States.Open"],
                    "range": {
                      "minimumValue": 1,
                      "maximumValue": 100
                    }
                  }  
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

SetRangeValueディレクティブ

SetRangeValueディレクティブをサポートすると、ユーザーがデバイスの機能のレベルを設定できます。

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

日本語
英語（すべて）

アレクサ、扇風機の風量を7にして
アレクサ、扇風機の風量を最大にして

Alexa, set the bedroom fan speed to 7.
Alexa, set the fan speed on the bedroom fan to maximum.

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

フィールド	説明	型
`rangeValue`	デバイスの機能に設定する値です。	数値

SetRangeValueディレクティブの例

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

SetRangeValue応答イベント

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

SetRangeValue応答イベントの例

{
  "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.RangeController",
        "instance": "Fan.Speed",
        "name": "rangeValue",
        "value": "7",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

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

AdjustRangeValueディレクティブ

AdjustRangeValueディレクティブをサポートすると、ユーザーがデバイスの機能のレベルを調整できます。

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

日本語
英語（すべて）

アレクサ、扇風機の風量を上げて
アレクサ、扇風機の風量を3弱めて

Alexa, turn up the bedroom fan speed.
Alexa, decrease the fan speed on the bedroom fan by 3.

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

フィールド	説明	型
`rangeValueDelta`	デバイスの機能の変化量です。ユーザーが量を指定しない場合は、`precision`が使用されます。	数値
`rangeValueDeltaDefault`	ユーザーが変化量を指定した場合はfalseです。	ブール値

AdjustRangeValueディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.RangeController",
      "instance": "Fan.Speed",
      "name": "AdjustRangeValue",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
      "rangeValueDelta": -3,
      "rangeValueDeltaDefault": false
    }
  }
}

AdjustRangeValue応答イベント

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

AdjustRangeValue応答イベントの例

{
  "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.RangeController",
        "instance": "Fan.Speed",
        "name": "rangeValue",
        "value": "4",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

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

状態レポート

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

ReportStateディレクティブをサポートすると、ユーザーがデバイスの機能について質問できます。

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

日本語
英語（すべて）

アレクサ、扇風機の風量は？

Alexa, what is the fan speed?

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.RangeController",
        "instance": "Fan.Speed",
        "name": "rangeValue",
        "value": "4",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "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.RangeController",
            "instance": "Fan.Speed",
            "name": "rangeValue",
            "value": "10",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {}
}

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

フィードバックを送信

Alexa.RangeControllerインターフェース

発話

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

rangeValueプロパティ

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

検出

検出応答の例

検出応答の例

ブラインドの検出応答の例

ディレクティブ

SetRangeValueディレクティブ

SetRangeValue応答イベント

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

AdjustRangeValueディレクティブ

AdjustRangeValue応答イベント

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

状態レポート

変更レポート

関連トピック

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