Discoveryインターフェース
ユーザーが初めてアプリの使用を開始すると、AlexaはAlexa.Discoveryインターフェースを介してDiscoverディレクティブを送信し、ビデオスキルでサポートされている機能を特定します。このDiscoverディレクティブへのレスポンスで、AlexaからLambda関数に送信されるディレクティブの種類が決まります。
たとえば、チャンネル変更をサポートしていることを指定した場合、「チャンネルをPBSに変えて」とユーザーが発話すると、AlexaはChannelControllerディレクティブを送信します。 しかし、このサポートを指定しない場合、Alexaはこのディレクティブを送信しません。
- Discoverディレクティブ
- Alexa Client Libraryにおける機能の指定
- Discoverディレクティブの例
- ペイロードの説明
- レスポンスの例
- ペイロードの説明
- capabilities配列
- KeypadControllerインターフェースの機能の宣言
Discoverディレクティブ
ユーザーがAlexaスキルをAmazonアカウントに関連付けると、AlexaはDiscoverディレクティブを送信します。それ以降、AlexaはDiscoverディレクティブを定期的に送信して、検出されたデバイスを更新します。Lambda関数がDiscoverディレクティブを受け取る際、ユーザー側で行う処理はありません。
Alexa Client Libraryにおける機能の指定
手順3： Alexa Client Libraryを統合するでAlexa Client LibraryをAndroidプロジェクトに統合する際、アプリでサポートされている機能をcapabilities配列で指定する必要があります。
// スキルでサポートされている機能のリストを作成します。
List<String> capabilities = new ArrayList<>();
capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);
Alexaは、Alexa Client LibraryにあるこのcapabilitiesリストとLambda関数を参照して、アプリでサポートされている機能を特定します。
機能については、後のcapabilities配列セクションで説明します。Alexa Client LibraryとLambdaで定義されている機能の名前は異なりますが、機能自体はほぼ同じです。
| Alexa Client Libraryの機能名 | ディレクティブの機能名 |
|---|---|
AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER |
Alexa.ChannelController |
AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER |
Alexa.RemoteVideoPlayer |
AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER |
Alexa.PlaybackController |
AlexaClientManager.CAPABILITY_SEEK_CONTROLLER |
Alexa.SeekController |
AlexaClientManager.CAPABILITY_KEYPAD_CONTROLLER |
Alexa.KeypadController |
Discoverディレクティブの例
Alexa Client Libraryを初期化する際に機能のサポートを指定するだけでなく、Lambda関数でもビデオスキルの機能を指定する必要があります。Lambda関数の作成について詳しくは、手順6： Lambdaパッケージを作成・デプロイするを参照してください。
Alexaから送信されLambda関数で処理する必要があるDiscoverディレクティブの例を以下に示します。
{
"directive": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "46e09424-9c8a-4868-9db5-6c851e967b32",
"name": "Discover",
"namespace": "Alexa.Discovery",
"payloadVersion": "3"
},
"payload": {
"scope": {
"token": "[ユーザーのOAuthトークン]",
"type": "BearerToken"
}
}
}
}
ペイロードの説明
payloadのフィールドについて次の表で説明します。
| フィールド | 説明 | データ型 |
|---|---|---|
scope（必須） |
リクエストの範囲（tokenおよびtypeプロパティが含まれます）。
|
オブジェクト |
token（必須） |
OAuth2ベアラートークン。
例： |
文字列 |
type（必須） |
スコープの種類（現在サポートされている値はBearerTokenです）。
例： |
列挙型 |
レスポンスの例
Lambda関数はDiscoverディレクティブを受信すると、Discover.Responseを送り返して、スキルでサポートしている機能を指定する必要があります（指定はcapabilities配列で行います）。
{
"event": {
"header": {
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion":"3",
“messageId”:“2aa731f1-b6dd-471c-98fe-3ac5fa5d6554”
},
"payload": {
"endpoints": [
{
"capabilities": [
{
"interface": "Alexa.RemoteVideoPlayer",
"type": "AlexaInterface",
"version": "1.0"
},
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackController",
"version": "3",
"supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous", "Rewind", "FastForward"]
},
{
"interface": "Alexa.SeekController",
"type": "AlexaInterface",
"version": "1.0"
},
{
"interface": "Alexa.ChannelController",
"type": "AlexaInterface",
"version": "1.0"
},
{
"interface": "Alexa.KeypadController",
"type": "AlexaInterface",
"version": "3",
"keys": [
"INFO", "MORE", "SELECT",
"UP", "DOWN", "LEFT", "RIGHT",
"PAGE_UP", "PAGE_DOWN", "PAGE_LEFT", "PAGE_RIGHT"
]
},
{
"interface": "Alexa.Launcher",
"type": "AlexaInterface",
"version": "3.1",
"configuration": {
"catalogs": [],
"targets": [
{
"name": "profile",
"identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw="
},
{
"name": "settings",
"identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw"
},
{
"name": "browse",
"identifier": "primevideo.Byb9lM7y5cjvtKF2q1i0samxtKc="
},
{
"name": "watchlist",
"identifier": "primevideo.OUlgBIlNyZkxB5+MPP+MPo/Yl5Y"
},
{
"name": "movies",
"identifier": "primevideo.zYYLxEVy5FSUC6oCrza6ly7FWLg"
}]
}
}
]
}
]
}
}
};
ペイロードの説明
レスポンスに含まれるpayloadオブジェクトを次の表に示します。
| フィールド | 説明 | データ型 |
|---|---|---|
endpoints（必須） |
ユーザーのデバイスクラウドアカウントに関連付けられたデバイスを表すエンドポイントオブジェクト配列。 | オブジェクト |
capabilities（必須） |
スキルがエンドポイントに対してサポートしている機能インターフェース。詳細については、以下の機能オブジェクトを参照してください。 | 機能オブジェクトの配列 |
interface（必須） |
デバイスのアクションを記述するAlexa.Interfaceの修飾名。
例： |
文字列 |
type（必須） |
スコープの種類（現在サポートされている値はBearerTokenです）。
例： |
列挙型 |
version（省略可能） |
エンドポイントでサポートしているインターフェースのバージョン。
例： |
文字列 |
cookie（省略可能） |
スキルアダプターで使用するデバイスに関する追加情報を表す、名前と値のペアで構成される文字列。このプロパティの内容は5000バイト以内に収める必要があります（Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません）。
例： |
オブジェクト |
extraDetail（省略可能） |
cookieオブジェクトのキー。
例： |
|
description（必須） |
デバイスの説明。会社名または実装を含む必要があります。この値は最大128文字までです（Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません）。
例： |
文字列 |
endpointId（必須） |
エンドポイントの識別子。たとえば、VSKTVなどです。注： ビデオスキル名と同じ値を入力することはできません。また、値の先頭にTEST_やPROD_を付けて、ビデオスキル名と明確に区別することをお勧めします。
例： |
文字列 |
friendlyName（必須） |
ビデオスキルの実装タイプを識別するための名前。この値は最大128文字までで、特殊文字や句読点を含めることはできません。注： ビデオスキル名と同じ値を入力しないでください。たとえば、ビデオスキルの名前が「ACME Media」の場合、フレンドリー名には「ACME Media」と入力しないでください。同じ名前を入力すると、エラーになります。名前に何らかの接頭辞を付けることをお勧めします（「TEST_ACME_Media」や「PROD_ACME_Media」など）。
例： |
文字列 |
manufacturerName（必須） |
デバイスのメーカーの名前。この値は最大128文字までです（Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません）。
例： |
文字列 |
capabilities配列
capabilities配列は、interface、type、version、supportOperationsの各プロパティをそれぞれに含むオブジェクトのリストです。たとえば、再生機能のサポートを宣言するcapabilities配列内の項目は次のようになります。
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackController",
"version": "3",
"supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous",
"Rewind", "FastForward"]
}
supportedOperationsプロパティを含んでいるインターフェースはAlexa.PlaybackControllerインターフェースだけです。
keysプロパティを含んでいるインターフェースは、Alexa.KeypadControllerインターフェースだけです。
ビデオスキルでサポートされている機能とその関連ディレクティブを次の表に示します。
| 機能 | 説明 |
|---|---|
Alexa.RemoteVideoPlayer |
ビデオスキルは、SearchAndPlayディレクティブやSearchAndDisplayResultsディレクティブなど、RemoteVideoPlayerインターフェースのディレクティブをサポートできます。これらのディレクティブを使用すると、ユーザーはビデオコンテンツの検索や再生を行えます。たとえば、「『ブレイキング・バッド』を検索して」や「アレクサ、『ブレイキング・バッド』を見せて」などです。 |
Alexa.PlaybackController |
ビデオスキルは、Alexa.PlaybackControllerインターフェースのディレクティブをサポートできます。このインターフェースは、オーディオまたはビデオコンテンツの再生、停止、ナビゲーションに使用されます。（「アレクサ、早送りして」や「アレクサ、停止して」など）。 PlaybackControllerインターフェースではsupportedOperationsプロパティも使用できます。supportedOperationsに使用可能な値は、 Play、Pause、Stop、StartOver、Next、Previous、Rewind、FastForwardです。 |
Alexa.SeekController |
ビデオスキルは、Alexa.SeekControllerインターフェースのディレクティブをサポートできます。このインターフェースを使用すると、メディアタイムラインの特定の位置に移動できます。たとえば、「アレクサ、60秒早送りして」や「アレクサ、5分早戻しして」などです（アプリでメディアアイテムの早送りまたは早戻しのみが可能で、タイムラインの別のポイントまでシークできない場合は、代わりにPlaybackControllerインターフェースを実装します）。 |
Alexa.ChannelController |
ビデオスキルは、Alexa.ChannelControllerインターフェースのディレクティブをサポートできます。このインターフェースは、エンターテインメントデバイスのチャンネルを変更または進めるために使用されます。たとえば、「アレクサ、チャンネルをPBSに変えて」などです。 |
Alexa.KeypadController |
ビデオスキルは、Alexa.KeypadControllerインターフェースのディレクティブをサポートできます。このインターフェースは、左右または上下へのスクロールやフォーカスされているウィジェットの選択に使用されます。たとえば、「アレクサ、右にスクロールして」などです。 前のコード例に従って、ビデオスキルでサポートしているキーのリスト（keys）を指定します。キー値には、UP、DOWN、LEFT、RIGHT、SELECT、PAGE_UP、PAGE_DOWN、PAGE_LEFT、PAGE_RIGHT、INFO、MOREがあります。詳細については、KeypadControllerインターフェースの機能の宣言を参照してください。KeypadControllerを使用するには、Alexa Client Libraryバージョン1.4.5以降が必要です。 |
Alexa.Launcherインターフェース （バージョン3.1以降のみ） |
ビデオスキルは、バージョン3.1以降のAlexa.Launcherインターフェースのディレクティブをサポートできます。このインターフェースは、スキル内の任意の識別子やショートカットへの移動に使用されます。たとえば、「アレクサ、ウォッチリストに移動して」（ビデオスキルやアプリが起動中の場合）などです。レスポンスの例セクションを参考にして、ショートカットリストの構造を作成します。 |
KeypadControllerインターフェースの機能の宣言
アプリ内の音声ナビゲーションと選択で説明しているように、Fire TVではデフォルトで、アプリ内での音声によるスクロールと選択が可能です。DiscoveryレスポンスでKeypadControllerインターフェースの機能に対するサポートを指定しない場合、VSKはデフォルトのアプリ内音声ナビゲーションおよび選択機能にフォールバックします。
一方、DiscoveryレスポンスでKeypadControllerインターフェースの機能に対するサポートを指定した場合、デフォルトのアプリ内音声ナビゲーションおよび選択機能は無効になり、音声によるスクロールと選択は、Lambdaで受信するKeyStrokeディレクティブへの応答を通じてのみ行われます。
KeypadControllerのサポートを宣言する場合は、ビデオスキルでサポートするキーのリストを指定します。キー値には、 UP、DOWN、LEFT、RIGHT、SELECT、PAGE_UP、PAGE_DOWN、PAGE_LEFT、PAGE_RIGHT、INFO、MOREがあります。いずれかのキーコマンドのサポートを宣言すると、すべてのキーコマンドのアクションを管理していると見なされます。つまり、一部のキーコマンドのみをサポートして、それ以外をサポートしないという宣言はできません。たとえば、UPを宣言しない場合でも、Alexaは、UP値を含んだkeystrokeペイロードを送信します。サポートされていないUP機能を補うために、デフォルトのアプリ内音声ナビゲーションおよび選択機能が働くことはありません。
Last updated: 2022年6月22日
