?
サポート

Alexa.PercentageControllerインターフェース

Alexa.PercentageControllerインターフェース

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

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

ディレクティブ

このインターフェースの制御とクエリのディレクティブは、次の言語を対象とするスキルでサポートされています。

  • 英語(米国)
  • 英語(英国)
  • 英語(インド)
  • ドイツ語
  • 日本語

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

SetPercentage

エンドポイントにパーセンテージ値を設定することを要求します。

「Alexa、名前を数値パーセントに設定して」

「Alexa, set name to number percent」

リクエストの例:

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

AdjustPercentage

デバイス設定のパーセンテージ値の増減を要求します。

「Alexa、端末名を数値パーセント増やして」

「Alexa、端末名を数値パーセント減らして」

「Alexa, increase device name by number percent」

「Alexa, decrease device name by number percent」

リクエストの例:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "AdjustPercentage",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "percentageDelta": -20
    }
  }
}

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

プロパティとイベント

このインターフェースでは、次のいずれかの応答を使用する必要があります。

  • 同期的。つまり、Lambda関数からAlexaにResponseイベントを送信します。
  • 非同期的。つまり、AlexaイベントゲートウェイにResponseイベントを送信します。非同期応答の際には、ユーザーを識別する認可を受けたトークンを含むscope要素と、応答するディレクティブを識別する correlation トークンが必要になります。

Responseを送信するときには、メッセージの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": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

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

追加のサンプルコード

リクエストの例と応答メッセージについては、AlexaスマートホームGitHubリポジトリを参照してください。

PercentageController

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