Discoveryインターフェース

ユーザーが初めてアプリの使用を開始すると、AlexaはAlexa.Discoveryインターフェースを介してDiscoverディレクティブを送信し、ビデオスキルでサポートされている機能を特定します。このDiscoverディレクティブへのレスポンスで、AlexaからLambda関数に送信されるディレクティブの種類が決まります。

たとえば、チャンネル変更をサポートしていることを指定した場合、「チャンネルをPBSに変えて」とユーザーが発話すると、AlexaはChannelControllerディレクティブを送信します。しかし、このサポートを指定しない場合、Alexaはこのディレクティブを送信しません。

注： Discoverディレクティブは、クラウド側の統合でのみ使用されます。アプリのみの統合でも同じ情報の中継は行いますが、方法が異なります。詳細については、アプリのみの統合でサポートされる機能を参照してください。

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`

注：ここに記載されている機能の宣言は現在も有効ですが、これらの機能の構成が不要な場合にのみ使用できます。構成が必要な場合は、より詳細な機能ビルダーインターフェースを使用してください。これは、Alexa Client Library（クラウド側の統合専用）のパッケージに含まれています。このパッケージ内には、詳細が記載されたドキュメントも用意されています。

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ベアラートークン。例：`b68f05cc-6a25-4134`	文字列
`type` （必須）	スコープの種類（現在サポートされている値は`BearerToken`です）。例： `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`の修飾名。例： `Alexa.RemoteVideoPlayer`	文字列
`type` （必須）	スコープの種類（現在サポートされている値は`BearerToken`です）。例： `BearerToken`	列挙型
`version` （省略可能）	エンドポイントでサポートしているインターフェースのバージョン。例： `1.0`	文字列
`cookie` （省略可能）	スキルアダプターで使用するデバイスに関する追加情報を表す、名前と値のペアで構成される文字列。このプロパティの内容は5000バイト以内に収める必要があります（Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません）。例：`key1`	オブジェクト
`extraDetail` （省略可能）	`cookie`オブジェクトのキー。例：`key1`
`description` （必須）	デバイスの説明。会社名または実装を含む必要があります。この値は最大128文字までです（Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません）。例： `Amazon Streaming Media App`	文字列
`endpointId` （必須）	エンドポイントの識別子。たとえば、`VSKTV`などです。注：ビデオスキル名と同じ値を入力することはできません。また、値の先頭に`TEST_`や`PROD_`を付けて、ビデオスキル名と明確に区別することをお勧めします。例： `TEST_VSKTV`	文字列
`friendlyName` （必須）	ビデオスキルの実装タイプを識別するための名前。この値は最大128文字までで、特殊文字や句読点を含めることはできません。注：ビデオスキル名と同じ値を入力しないでください。たとえば、ビデオスキルの名前が「ACME Media」の場合、フレンドリー名には「ACME Media」と入力しないでください。同じ名前を入力すると、エラーになります。名前に何らかの接頭辞を付けることをお勧めします（「TEST_ACME_Media」や「PROD_ACME_Media」など）。例： `TEST_VSK_FTV`	文字列
`manufacturerName` （必須）	デバイスのメーカーの名前。この値は最大128文字までです（Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません）。例： `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`インターフェースのディレクティブをサポートできます。このインターフェースは、左右または上下へのスクロールやフォーカスされているウィジェットの選択に使用されます。たとえば、「アレクサ、右にスクロールして」などです。上記のコード例に従って、ビデオスキルでサポートしているキーのリストを指定します。キー値には、 `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機能を補うために、デフォルトのアプリ内音声ナビゲーションおよび選択機能が働くことはありません。