Discoveryディレクティブ


Discoveryディレクティブ

Amazonは、ビデオスキルでサポートされる機能を特定するために、Discovery APIを通じてDiscoverディレクティブを送信します。Discoveryディレクティブへのレスポンスによって、AlexaからLambda関数に送信されるディレクティブの種類が決まります。

たとえば、チャンネル変更のサポートを指定している場合、「チャンネルをPBSに変えて」とユーザーが発話すると、"type": "Channel"ペイロードを含んだGetPlayableItemsディレクティブがAlexaから送信されます。 一方、この機能のサポートを指定していない場合、Alexaからこのディレクティブは送信されません。

Discoveryディレクティブ

ユーザーがAlexaスキルをAmazonアカウントに関連付けると、AlexaはDiscoveryディレクティブを送信します。その後、AlexaはDiscoveryディレクティブを定期的に送信して、検出されたデバイスを更新します。

Discoverディレクティブを受信したら、スキルがサポートしているディレクティブを指定する必要があります。サポートされているオペレーションは、supportedOperations配列で指定します。

(Fire TVの実装では、Alexa Client Libraryを初期化する際にAndroidアプリの機能サポートも指定しましたが、マルチモーダル実装では、Lambda関数で機能サポートを指定するだけで構いません。)

Discoverの例

Alexaから送信されるDiscoverディレクティブの例を次に示します。

{
    "directive": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover",
            "payloadVersion": "3",
            "messageId": "a1dccea0-fe52-45ca-9ed9-a03a45be6fb6"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "1bdaa2eb-4aa3-d0dc-fb10-7a5513981cf8"
            }
        }
    }
}

ペイロードの説明

payloadのフィールドについて次の表で説明します。

ペイロードの説明
フィールド 説明 データ型
scope
(必須)
リクエストのスコープ。tokenおよびtypeプロパティが含まれます。 オブジェクト
token
(必須)
OAuth2ベアラートークン。

例:b68f05cc-6a25-4134

文字列
type
(必須)
スコープのタイプ。現在サポートされている値はBearerTokenです。

例: BearerToken

列挙型

レスポンスの例

Discoverディレクティブに対するレスポンス(Discover.Response)の例を次に示します。サポートされるオペレーションをレスポンスで指定します。

{
"event": {
    "header" : {
        "messageId" : "directive.header.messageId",
        "name" : "Discover.Response",
        "namespace": "Alexa.Discovery",
        "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [{
              "endpointId": "ALEXA_VOICE_SERVICE_EXTERNAL_MEDIA_PLAYER_VIDEO_PROVIDER",
              "endpointTypeId": "TEST_VSK_MM",
              "manufacturerName": "TEST_VSK_MM",
              "friendlyName": "TEST_VSK_MM",
              "description": "TEST_VSK_MM",
              "displayCategories": ["APPLICATION"],
              "cookie": {},
              "capabilities": [{
                      "type": "AlexaInterface",
                      "interface": "Alexa.RemoteVideoPlayer",
                      "version": "1.0"
                  }, {
                      "type": "AlexaInterface",
                      "interface": "Alexa.PlaybackController",
                      "version": "1.0"
                  }, {
                      "type": "AlexaInterface",
                      "interface": "Alexa.SeekController",
                      "version": "1.0"
                  }, {
                      "type": "AlexaInterface",
                      "interface": "Alexa.ChannelController",
                      "version": "1.0"
                  },
                  {
                      "type": "AlexaInterface",
                      "interface": "Alexa.MultiModalLandingPage",
                      "version": "1.0"
                  }
              ]
          }]
        }
}
};

ペイロードの説明

ペイロードの説明
フィールド 説明 データ型
endpoints
(必須)
ユーザーのデバイス制御クラウドアカウントに関連付けられたデバイスを表すエンドポイントオブジェクトの配列。 オブジェクト
capabilities
(必須)
スキルがエンドポイントに対してサポートしている機能インターフェイス。詳細については、後述の機能オブジェクトを参照してください。 機能オブジェクトの配列
interface
(必須)
デバイスのアクションを記述するAlexa.Interfaceの修飾名。

例: Alexa.RemoteVideoPlayer

文字列
type
(必須)
スコープのタイプ。現在サポートされている値はBearerTokenです。

例: BearerToken

列挙型
version
このエンドポイントでサポートしているインターフェイスのバージョンを示します。

例: 1.0

文字列
cookie
スキルアダプターで使用するデバイスに関する追加情報を表す、名前と値のペアで構成される文字列。このプロパティの内容は5000バイト以内に収める必要があります(Amazonではこのフィールドは使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。

例:key1

オブジェクト
extraDetail
cookieオブジェクトのキー。

例:key1

description
(必須)
デバイスの説明。会社名または実装を含む必要があります。この値の最大文字数は128文字です(Amazonではこのフィールドは使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。

例: Amazonストリーミングメディアアプリ

文字列
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配列には、interfacetypeversionsupportOperationsの各プロパティをそれぞれに含むオブジェクトのリストを格納できます。たとえば、再生機能のサポートを宣言するcapabilities配列の項目は次のようになります。

{
    "type": "AlexaInterface",
    "interface": "Alexa.PlaybackController",
    "version": "3",
    "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous",
      "Rewind", "FastForward"]
}

supportedOperationsプロパティを含むインターフェイスは、Alexa.PlaybackControllerインターフェイスだけです。

ビデオスキルでサポートされている機能とその関連ディレクティブについて次の表で説明します。

機能 説明
Alexa.RemoteVideoPlayer SearchAndPlayディレクティブとSearchAndDisplayResultsディレクティブをスキルでサポートできます。これらのディレクティブを使用すると、ユーザーはビデオコンテンツの検索や再生を行うことができます(「アレクサ、『ブレイキング・バッド』を検索して」や「アレクサ、『ブレイキング・バッド』を見せて」など)。
Alexa.PlaybackController オーディオまたはビデオコンテンツの再生、停止、ナビゲーションに使用される再生コントロールのディレクティブをスキルでサポートできます(「アレクサ、早送りして」や「アレクサ、停止して」など)。 上記のように、Alexa.PlaybackControllerインターフェイスではsupportedOperationsプロパティも使用できます。使用できるプロパティは、PlayPauseStopStartOverNextPreviousRewindFastForwardです。
Alexa.SeekController シークコントロールディレクティブをスキルでサポートできます。このディレクティブを使用すると、ユーザーは、「アレクサ、早送りして」や「アレクサ、巻き戻して」ではなく、「アレクサ、60秒早送りして」や「アレクサ、5分巻き戻して」といったリクエストを使用してメディアタイムラインの特定の位置に移動できます(アプリでメディアアイテムの早送りまたは巻き戻しのみが可能で、タイムラインの別のポイントまでシークできない場合は、代わりにAlexa.PlaybackControllerインターフェイスを実装してください)。
Alexa.ChannelController ChangeChannelのディレクティブをビデオスキルでサポートできます。これらのディレクティブは、エンターテインメントデバイスのチャンネルを変更したり進めたりするために使用されます(「アレクサ、チャンネルをPBSに変えて」など)。
Alexa.MultiModalLandingPage ランディングページの設定をビデオスキルでサポートできます。たとえば、ユーザーが「ビデオホーム」と発話してビデオスキルをタップすると、ビデオのリストが表示されます。