Alexa.PercentageControllerインターフェース



Alexa.PercentageControllerインターフェース

PercentageControllerインターフェースは、パーセンテージで表現できるエンドポイントのプロパティを制御するために使用するメッセージを記述します。このインターフェースは、デバイスに適用される固有のコントローラーインターフェースが存在しない場合にのみ使用します。通常、できるだけ固有性の高いインターフェースを実装する必要があります。

たとえば、輝度値に固有のリクエストを処理する場合は、Alexa.BrightnessControllerを使用します。調光スイッチなどエンドポイントの電力レベルに固有のリクエストを処理するには、Alexa.PowerLevelControllerを参照してください。

ディレクティブ

このインターフェースの制御とクエリーのディレクティブは、以下の言語のスキルで使用できます。

  • 英語 - すべてのロケール
  • フランス語(フランス)
  • ドイツ語
  • イタリア語
  • 日本語
  • スペイン語(スペイン)

詳細については、スマートホームスキルを複数の言語で開発するを参照してください。

SetPercentage

エンドポイントにパーセンテージ値を設定するようリクエストします。

ユーザー: Alexa, set the device to ##%
ユーザー: Alexa, stelle Geräteame auf Anzahl Prozent
ユーザー:デバイスのグループを##%に設定して

リクエストの例:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "SetPercentage",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "percentage": 74
    }
  }
}
フィールド 説明 必須
percentage デバイスに設定するパーセンテージ値です。 0から100までの整数(両端の値を含む)

AdjustPercentage

デバイス設定のパーセンテージ値の増減をリクエストします。

ユーザー: Alexa, increase device name by ##%
ユーザー: Alexa, decrease device name by ##%
ユーザー: Alexa, erhöhe Gerätename um ##%
ユーザー: Alexa, reduziere Gerätename um ##%
ユーザー:デバイスを##%明るくしてください

リクエストの例:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "AdjustPercentage",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "percentageDelta": -20
    }
  }
}

フィールド 説明 必須
percentageDelta 変化させる量をパーセンテージで表します。明るさのパーセンテージを増減させるために使用する正または負の整数値です。たとえば、開始値が100でパーセンテージの差分が-3の場合、最終値は97になります。 -100から100までの整数(両端の値を含む)

プロパティとイベント

この機能では、次のいずれかの応答を使用する必要があります。

  • 同期的に、Lambda関数からAlexaにResponseイベントを送信します。
  • 非同期的に、AlexaイベントゲートウェイにResponseイベントを送信します。非同期的に応答する場合、認可トークンにscopeを含めてユーザーを識別し、相関トークンを含めて応答先のディレクティブを識別する必要があります。

応答を送信する場合、メッセージのcontextにインターフェースのプロパティの状態を含めます。

プロパティ

プロパティ名 説明
percentage Percentage アプライアンス設定のパーセンテージ値です。たとえば、輝度、速度、電力レベルなどの値を指定できます。値は、0~100までの範囲(両端の値を含む)の整数です。

応答

パーセンテージのディレクティブが正常に処理された場合、Responseイベントで応答する必要があります。

応答の例

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.PercentageController",
      "name": "percentage",
      "value": 74,
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 1000
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

何らかの理由によりユーザーのリクエストを完了できない場合、エラー応答を返す必要があります。詳細については、Alexa.ErrorResponseを参照してください。

その他のサンプルコード

リクエストと応答のサンプルについては、AlexaスマートホームのGitHubリポジトリで以下を参照してください。

PercentageController

インターフェース 説明
Alexa.BrightnessController 照明の輝度をパーセンテージで設定します。