Alexa.PercentageControllerインターフェース3

Alexa.PercentageControllerインターフェース3

AlexaスキルにAlexa.PercentageControllerインターフェースを実装すると、ユーザーはデバイスのパーセンテージで表せるプロパティを制御できます。スマートホームスキルの詳細については、スマートホームスキルを理解するを参照してください。

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

PercentageControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

発話

Alexa.PercentageControllerインターフェースを使用する場合、音声対話モデルは既にビルドされています。ユーザーが次のいずれかの発話をしたら、Alexaがそれに対応するディレクティブをスキルに送信します。

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

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ätename> auf dreißig Prozent.
Alexa, erhöhe <Gerätename> um zehn Prozent.
Alexa, reduziere <Gerätename> um zwanzig Prozent.

Alexa, règle le salon à trente pour cent.
Alexa, augmente le salon de dix pour cent.
Alexa, réduis le salon de vingt pour cent.

Alexa, {डिवाइस का नाम} को तीस प्रतिशत पर सेट करें।
Alexa, {डिवाइस का नाम} को दस प्रतिशत बढ़ा दें।
Alexa, {डिवाइस का नाम} को बीस प्रतिशत घटाएं।

Alexa, imposta il salotto al trenta percento.
Alexa, aumenta il salotto del dieci percento.
Alexa, diminuisci il salotto del venti percento.

アレクサ、＜device name＞を30パーセントに設定して
アレクサ、＜device name＞を10パーセント上げて
アレクサ、＜device name＞を20パーセント下げて

Alexa, coloque a luz da cozinha em trinta por cento.
Alexa, ajusta a luz do quarto para trinta por cento.
Alexa, Alexa, aumente a luz da sala em dez por cento.
Alexa, Alexa, aumente o brilho da luz da sala em dez por cento.
Alexa, Alexa, diminua a luz da sala em dez por cento.
Alexa, diminua o brilho da luz da sala em dez por cento.

Alexa, configura el dispositivo al treinta por ciento.
Alexa, sube la luz en un diez por ciento.
Alexa, disminuye la luz en un veinte por ciento.

Alexa, zet de <device name> op dertig procent.
Alexa, verhoog <device name> met tien procent.
Alexa, verlaag <device name> met twintig procent.

出力可能なプロパティ

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

検出

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

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

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

Alexaにデバイスの健全性を通知する場合、Alexa.EndpointHealthインターフェースも実装してください。

検出応答の例

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

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "エンドポイントの一意のID",
          "manufacturerName": "エンドポイントのメーカー名",
          "description": "Alexaアプリに表示される説明",
          "friendlyName": "Alexaアプリに表示されているデバイス名",
          "additionalAttributes":  {
            "manufacturer": "エンドポイントのメーカー名",
            "model" : "デバイスのモデル",
            "customIdentifier": "デバイスの任意のカスタム識別子"
          },
          "displayCategories": ["OTHER"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PercentageController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "percentage"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },            
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

Alexaは次のAlexa.PercentageControllerインターフェースディレクティブをスキルに送信します。

SetPercentageディレクティブ

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

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

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

Alexa, stelle <Gerätename> auf dreißig Prozent.

Alexa, règle le salon à trente pour cent.

Alexa, {डिवाइस का नाम} को तीस प्रतिशत पर सेट करें।

Alexa, imposta il salotto al trenta percento.

アレクサ、＜device name＞を30パーセントに設定して

Alexa, coloque a luz da cozinha em trinta por cento.
Alexa, ajusta a luz do quarto para trinta por cento.

Alexa, configura el dispositivo al treinta por ciento.

Alexa, zet de <device name> op dertig procent.

SetPercentageディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "SetPercentage",
      "messageId": "一意のバージョン4 UUID",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "percentage": 74
    }
  }
}

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

次の表は、SetPercentageディレクティブのペイロードの詳細を示しています。

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

SetPercentage応答

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

以下は、SetPercentage応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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 zehn Prozent.
Alexa, reduziere <Gerätename> um zwanzig Prozent.

Alexa, augmente le salon de dix pour cent.
Alexa, réduis le salon de vingt pour cent.

Alexa, {डिवाइस का नाम} को दस प्रतिशत बढ़ा दें।
Alexa, {डिवाइस का नाम} को बीस प्रतिशत घटाएं।

Alexa, aumenta il salotto del dieci percento.
Alexa, diminuisci il salotto del venti percento.

アレクサ、＜device name＞を10パーセント上げて
アレクサ、＜device name＞を20パーセント下げて

Alexa, aumente a luz da sala em dez por cento.
Alexa, aumente o brilho da luz da sala em dez por cento.
Alexa, diminua a luz da sala em dez por cento.
Alexa, diminua o brilho da luz da sala em dez por cento.

Alexa, sube la luz en un diez por ciento.
Alexa, disminuye la luz en un veinte por ciento.

Alexa, verhoog <device name> met tien procent.
Alexa, verlaag <device name> met twintig procent.

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

次の表は、AdjustPercentageディレクティブのペイロードの詳細を示しています。

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

AdjustPercentageディレクティブの例

以下は、Alexaがスキルに送信するAdjustPercentageディレクティブの例です。

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "AdjustPercentage",
      "messageId": "一意のバージョン4 UUID",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "percentageDelta": -20
    }
  }
}

AdjustPercentage応答

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

以下は、AdjustPercentage応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "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": "一意の識別子、バージョン4 UUIDが望ましい",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0ベアラートークン"
      },
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.PercentageController",
            "name": "percentage",
            "value": 65,
            "timeOfSample": "2024-05-01T19:20:05.05Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2024-05-01T19:10:22.05Z",
    "uncertaintyInMilliseconds": 0
  }
}

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

最終更新日: 2024 年 12 月 09 日