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

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

ユーザーがデバイスのモード設定を制御できるように、AlexaスキルにAlexa.ModeControllerインターフェースを実装しましょう。Alexa.ModeControllerインターフェースを使用すると、洗濯乾燥機の洗浄サイクルモードなど、ユーザーがリストのいずれかの値に設定できるデバイスのプロパティをモデル化できます。値のリストには順序を設定できますが、必須ではありません。Alexa.ModeControllerインターフェースは汎用コントローラーインターフェースです。

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

Alexa.ModeControllerインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。

メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

発話

Alexa.ModeControllerインターフェースではプリビルド音声対話モデルを使用します。以下に、ユーザーの発話の例を示します。

Alexa, what's the wash setting on the washer?
Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.
Alexa, increase the water temperature on the washer.

アレクサ、扇風機は何に設定されている？
アレクサ、洗濯機をデリケートモードにして
アレクサ、洗濯モードをドライに設定して
アレクサ、洗濯機の水位を上げて

セマンティクスを使用すると、発話を追加できます。以下は、セマンティクスを使用して有効にしたユーザーの発話の例です。

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

Alexa, fahre das Rollo in der Küche hoch.
Alexa, fahre das Küchenrollo hoch.
Alexa, fahr das Wohnzimmer-Rollo runter.
Alexa, fahre die Rollläden im Wohnzimmer runter.

アレクサ、ゴミ箱のふたを開けて
アレクサ、ブラインドを閉めて
アレクサ、シェードを上げて
アレクサ、プロジェクタースクリーンを下げて

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

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

Modeプロパティ

Alexa.ModeControllerインターフェースでは、プライマリプロパティとしてmodeプロパティを使用します。プロパティ値は文字列です。Modeオブジェクトは、そのモードで許容される値を定義します。

エンドポイントは複数のモードに対応しています。モードを区別するために、常にinstanceアトリビュートを含める必要があります。このアトリビュートはモードの名前を定義します。instance名は検出応答で識別します。

Modeプロパティの例

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

{
    "namespace": "Alexa.ModeController",
    "name": "mode",
    "instance": "Washer.WashTemperature",
    "value": "WashTemperature.Cold"
}

Modeオブジェクト

Modeオブジェクトには、モードで許容される値を指定します。検出応答で、supportedModes配列に少なくとも2つのModeオブジェクトを含めます。

以下は、2つのModeオブジェクトを含むsupportedModes配列の例です。

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

"supportedModes": [
  {
    "value": "WashCycle.Normal",
    "modeResources": {
    }
  },
  {
    "value": "WashCycle.Delicates",
    "modeResources": {
    }
  }
]

以下の表は、Modeオブジェクトのプロパティを示しています。

フィールド 説明 型
value モード値の名前です。 String
modeResources ユーザーがモードの操作に使用できるフレンドリー名です。 ModeResourcesオブジェクト

ModeResourcesオブジェクト

ModeResourcesオブジェクトを使用して、ユーザーがモード値の操作に使用できる一連のフレンドリー名を指定します。最初のフレンドリー名が、Alexaアプリに表示される名前です。詳細については、リソースとアセットを参照してください。

以下は、洗濯機のデリケート洗浄サイクルに使用するモードリソースの例です。ユーザーは、「アレクサ、洗浄サイクルをニットに設定して」などのフレーズを使用できます。

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

"modeResources":
{
  "friendlyNames": [
    {
      "@type": "asset",
      "value": {
        "assetId": "Alexa.Value.Delicate"
      }
    },
    {
      "@type": "text",
      "value": {
        "text": "デリケート",
        "locale": "ja-JP"
      }
    },
    {
      "@type": "text",
      "value": {
        "text": "ニット",
        "locale": "ja-JP"
      }
    },
    {
      "@type": "text",
      "value": {
        "text": "Ciclo delicado",
        "locale": "es-MX"
      }
    },
    {
      "@type": "text",
      "value": {
        "text": "Cycle délicat",
        "locale": "fr-CA"
      }
    }
  ]
}

セマンティクス

セマンティクスを使用すると、ユーザー発話の追加やデバイスに注意を向けてもらう必要がある場合の通知など、追加の機能を有効にすることができます。セマンティクスを使用するには、検出のセクションで説明するように、検出応答にsemanticsオブジェクトを含めます。

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

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

オプションで、セマンティクスを使用して発話を追加できます。セマンティクスを使用する場合は、「開いて」、「閉じて」、「上げて」、「下げて」といったフレーズを、Alexa.ModeControllerのディレクティブであるSetModeとAdjustModeに手動でマップします。たとえば、ガレージドアオープナーの場合、「開けて」をSetModeディレクティブにマップできます。

セマンティクスを使用して通知を有効にする

セマンティクスを使用して、デバイスに注意を向けてもらう必要がある場合にユーザーに通知することができます。通知の形式は、<デバイスのフレンドリー名>が<状態>となります。たとえば、自動運転掃除機に何かが詰まった場合、Alexaは次のようにユーザーに通知します： 「掃除機が詰まっています」

通知を有効にするには、AlexaスキルにAlexa.ProactiveNotificationSourceインターフェースを実装します。サポートする状態を指定するには、検出応答にsemanticsオブジェクトを含め、modeプロパティをAlexa.States.StuckなどのAlexa.States値のいずれかにマップします。通知をトリガーするには、デバイスの状態の変更をレポートするAlexa.ChangeReportを送信します。詳細については、Alexa.ProactiveNotificationSourceインターフェースを参照してください。

検出

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

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

Alexa user identificationを使用するConnected Vehicleの場合は、検出レスポンスにdirectiveConfigurationsを含めて、認証の信頼レベルとポリシー名を設定します。詳細については、directiveConfigurationsを参照してください。

ユーザーが変更できないエンドポイントのプロパティは、nonControllableをtrueに設定することでモデル化できます。たとえば、洗濯機が自動で洗い、すすぎ、脱水に移行する場合、洗浄サイクルの変更を許可せずに、現在の洗浄サイクルをユーザーにレポートできます。

capabilities配列の各Alexa.ModeControllerエントリに、オプションでsemanticsオブジェクトを含めることができます。詳細については、セマンティクスを使用して発話を追加するおよびセマンティクスを使用して通知を有効にするを参照してください。

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

capabilities配列

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

フィールド 説明 型
instance Washer.WashCycleやWasher.WashTemperatureといったモード名です。 String
capabilityResources ユーザーがモードとの対話に使用できるフレンドリー名です。
インスタンスのフレンドリー名の通知を有効にする場合は、@typeを含めてtextに設定します。		 CapabilityResourcesオブジェクト
configuration.ordered モード名が順序付けされている場合はtrueに設定し、それ以外の場合はfalseに設定します。たとえば、洗浄温度モードは、低温、中温、高温の順に並べることができます。
順序付けされているモードはAdjustModeディレクティブをサポートします。		 Boolean
configuration.
supportedModes		 受け入れられるモード値のリストを指定します。
2つ以上のモードオブジェクトを含める必要があります。
順序付けされたモード値を配列に昇順で列挙します。		 Modeオブジェクトの配列

検出応答の例

洗濯乾燥機の例

以下は、次の3つのインスタンスで定義される3つのモードをサポートする洗濯乾燥機に対するDiscover.Responseメッセージの例です： Washer.WashCycle、Washer.CurrentWashCycle、Washer.WashTemperature。

ブラインドのセマンティクスの例

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

Alexa.ModeControllerインターフェースは、次のロケールでブラインドを制御するスキルに使用できます：de-DE、en-AU、en-GB、en-IN、en-US、es-ES、es-MX、es-US、it-IT、ja-JP。

ガレージドアオープナーのセマンティクスの例

以下は、Alexa.ModeControllerインターフェースをサポートするガレージドアオープナーに対するDiscover.Responseメッセージの例です。この例ではセマンティクスを使用しています。デバイスがガレージドアオープナーの場合、Alexa.ModeControllerインターフェースとGARAGE_DOOR表示カテゴリーの両方を使う必要があります。

ガレージドアデバイスの場合、ユーザーがガレージドアを開けるよう言うと、Alexaはガレージドアを開ける前に「確認コードは何ですか？」とたずねます。

Alexa.ModeControllerインターフェースは、次のロケールでガレージドアを制御するスキルに使用できます：de-DE, en-GB, en-US, es-ES, fr-FR, it-IT。

ディレクティブ

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

SetModeディレクティブ

SetModeディレクティブをサポートすると、ユーザーがデバイスのモードを設定できます。

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

Alexa, set the wash cycle to cottons.
Alexa, set the wash setting on the washer to normal.

アレクサ、洗濯機をデリケートモードにして
アレクサ、洗濯モードをドライに設定して

SetModeディレクティブの例

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

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

SetModeディレクティブペイロード

プロパティ 説明 型 必須

mode

デバイスに設定するモードです。

String

◯

SetMode応答

SetModeディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。

contextオブジェクトに、変更されたすべてのプロパティの値を含めます。レポートするmodeプロパティごとに、instanceアトリビュートを含める必要があります。

次の例は、Washer.WashCycleモードの値が変更されたことをレポートしています。

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

{
  "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.ModeController",
        "instance": "Washer.WashCycle",
        "name": "mode",
        "value": "WashCycle.Normal",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

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

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

AdjustModeディレクティブ

順序付けされているモードの場合は、AdjustModeディレクティブをサポートし、ユーザーがデバイスのモードを調整できるようにします。

このディレクティブの検出応答でconfiguration.orderedをtrueに設定すると、ユーザーは指定された差分だけモードを増減できます。このディレクティブは、現在のモードによってリクエストを限定することはありません。増減リクエストを適切に処理することで、複数のモード間を遷移することができます。

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

Alexa, increase the water temperature on the washer.

アレクサ、洗濯機の水温を上げて

AdjustModeディレクティブの例

以下の例は、Alexaがスキルに送信するAdjustModeディレクティブを示しています。

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

AdjustModeディレクティブペイロード

プロパティ 説明 型 必須

modeDelta

モードの変更量です。デフォルトは1です。

Integer

✕

AdjustMode応答

AdjustModeディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。

contextオブジェクトに、変更されたすべてのプロパティの値を含めます。レポートするmodeプロパティごとに、instanceアトリビュートを含める必要があります。

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

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

{
  "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.ModeController",
        "instance": "Washer.WashTemperature",
        "name": "mode",
        "value": "WashTemperature.Warm",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

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

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

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするために、ReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。状態レポートの詳細については、状態および変更レポートについてを参照してください。

この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態が含まれます。レポートするmodeプロパティごとに、instanceアトリビュートを含める必要があります。検出応答で、状態が照会可能なプロパティとinstance名を識別します。

デバイスの電源がオフになっているなど、モードがセットされていない場合、modeプロパティをnullとしてレポートします。

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

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

Alexa, what's the current washer cycle?

アレクサ、洗濯機のモードは何にセットされている？

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.ModeController",
        "instance": "Washer.WashCycle",
        "name": "mode",
        "value": "WashCycle.Delicates",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

ChangeReportには、ペイロードオブジェクトで変更されたすべてのプロパティ値が含まれます。レポートするmodeプロパティごとにinstanceアトリビュートを含める必要があります。検出応答で、プロアクティブにレポートするプロパティとinstance名を識別します。

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.ModeController",
            "instance": "Washer.WashTemperature",
            "name": "mode",
            "value": "WashTemperature.Hot",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T16:20:50Z",
    "uncertaintyInMilliseconds": 0
  }
}

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

最終更新日: 2022 年 11 月 08 日