Alexa.ChannelControllerインターフェース



Alexa.ChannelControllerインターフェース

ユーザーがエンターテイメントデバイス用のチャンネルを変更または加算できるように、AlexaスマートホームスキルにAlexa.ChannelControllerインターフェースを実装しましょう。エンターテイメントデバイスのスキルの詳細については、エンターテイメントデバイス用のスマートホームスキルを作成するを参照してください。

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

発話

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

Alexa, change the channel to 200 on the Living Room TV.
Alexa, change the channel to PBS on the TV.
Alexa, next channel on the Living Room TV.
Alexa, channel up on the TV.
Alexa, channel down on the TV.

アレクサ、チャンネル4に変えて
アレクサ、テレビをチャンネル1にして
アレクサ、次のチャンネル
アレクサ、前のチャンネルに戻って

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

プロパティ

channelオブジェクト

Alexa.ChannelControllerインターフェースでは、プライマリプロパティとしてchannelプロパティを使用します。プロパティ値はオブジェクトです。channelプロパティを使用して、番号、コールサイン、系列コールサインでチャンネルを指定します。

channelオブジェクトの詳細

フィールド 説明
number チャンネル番号(1や6など)です。 文字列
callSign チャンネルのコールサイン(NHKなど)です。 文字列
affiliateCallSign チャンネルの現地の系列コールサイン(JOBH-DTVなど)です。 文字列
uri チャンネルのURI(「entity://provider/channel/12307」など)です。 文字列

channelオブジェクトの例

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

{
   "name":"channel",
   "value": {
     "number": "9",
     "callSign": "NHK",
     "affiliateCallSign": "JOBH-DTV"
  }
}

channelMetadataオブジェクト

channelMetadataプロパティはチャンネルの追加情報を指定します。

channelMetadataオブジェクトの詳細

フィールド 説明
name チャンネルの別名(「日本放送協会」など)です。 文字列
image チャンネルの画像またはロゴのURLです。 文字列

channelMetadataオブジェクトの例

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

{
   "name":"channelMetadata",
   "value": {
     "name": "<チャンネルの別名>",
     "image": "<画像のURL>"
  }
}

検出

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

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

TVSTREAMING_DEVICEGAME_CONSOLEなどの適切な表示カテゴリーを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。

検出応答の例

以下は、Alexa.ChannelControllerインターフェースとAlexa.PowerControllerインターフェースをサポートするテレビへのDiscover.Responseメッセージの例です。テレビ用の推奨インターフェースの一覧については、スマートホームスキル用のデバイステンプレートを参照してください。

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

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "テレビメーカーのスマートテレビ",
          "friendlyName": "リビングのテレビ",
          "displayCategories": ["TV"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ChannelController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "channel"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

ChangeChannelディレクティブ

ChangeChannelディレクティブをサポートすると、ユーザーはチャンネル番号やコールサインを指定してデバイスのチャンネルを変更できます。

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

Alexa, change channel to 200 on Living Room TV.

Alexa, wechsel auf Wohnzimmer TV zu Kanal zweihundert.

アレクサ、テレビのチャンネルを5にして

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

フィールド 説明
channel デバイスの変更先のチャンネルです。 channelオブジェクト
channelMetadata デバイスの変更先のチャンネルについての追加情報です。 channelMetadataオブジェクト

ChangeChannelディレクティブの例

次の例は、Alexaがスキルに送信するChangeChannelディレクティブを示します。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "ChangeChannel",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {
      "channel": {
        "number": "9",
        "callSign": "NHK",
        "affiliateCallSign": "JOBH-DTV",
        "uri": "<チャンネルのURI>"
      },
      "channelMetadata": {
        "name": "<チャンネルの別名>",
        "image": "<画像のURL>"
      }
    }
  }
}

ChangeChannel応答イベント

ChangeChannelディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、変更されたすべてのプロパティの値を含めます。

ChangeChannel応答イベントの例

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ChannelController",
        "name": "channel",
        "value": {
          "number": "9",
          "callSign": "NHK",
          "affiliateCallSign": "JOBH-DTV"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

ChangeChannelディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

SkipChannelsディレクティブ

SkipChannelsディレクティブをサポートすると、デバイスのチャンネルをユーザーが段階的に変更できます。正の数値で1段階上がり、負の数値で1段階下がります。

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

Alexa, next channel on Living Room TV
Alexa, channel up on Living Room TV
Alexa, channel down on Living Room TV

Alexa, nächsten Kanal auf Wohnzimmer TV
Alexa, einen Kanal vor auf Wohnzimmer TV
Alexa, einen Kanal zurück auf Wohnzimmer TV

アレクサ、次のチャンネルに行って
アレクサ、前のチャンネルに戻って

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

フィールド 説明
channelCount チャンネルの増分を指定する数値です。正の数値で上がり、負の数値で下がります。 整数。現在指定できる値は1と-1のみです。

SkipChannelsディレクティブの例

次の例は、Alexaがスキルに送信するSkipChannelsディレクティブを示します。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "SkipChannels",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "payload": {
      "channelCount" : 1
    }
  }
}

SkipChannels応答イベント

SkipChannelsディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、変更されたすべてのプロパティの値を含めます。

SkipChannels応答イベントの例

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ChannelController",
        "name": "channel",
        "value": {
          "number": "7",
          "callSign": "CBS",
          "affiliateCallSign": "KIRO"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

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

SkipChannelsディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

状態レポート

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

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.ChannelController",
        "name": "channel",
        "value": {
          "number": "7",
          "callSign": "CBS",
          "affiliateCallSign": "KIRO"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、スマートホームスキルの状態レポートについてを参照してください。

ChangeReportイベントの例

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

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "VOICE_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ChannelController",
            "name": "channel",
            "value": {
              "number": "9",
              "callSign": "NHK",
              "affiliateCallSign": "JOBH-DTV"
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}