APIリファレンスの概要（VSK Echo Show）
ビデオスキルのディレクティブは、AlexaからLambda関数に送信されます。ディレクティブは、特定のアクション（ビデオのメタデータの取得など）の実行に関する命令を含むJSONメッセージです。名前とペイロードが異なるさまざまなディレクティブが存在します。Lambda関数は、受信したディレクティブを処理して、所定のJSON形式に準拠したレスポンスを返す必要があります。一般的には、Alexaから送信される「ディレクティブ」と呼ばれるリクエスト（JSON形式）と、Lambdaから送信されるレスポンス（同じくJSON形式）が基本モデルとなります。つまり、JSON形式でリクエストを受け取り、JSON形式でレスポンスを返します。
マルチモーダルデバイスでサポートされる発話
概要で説明されているように、マルチモーダルデバイスでは以下の発話がサポートされています。
- 検索：
VideoName、ActorName、GenreNameなどの条件を使用して、表示するコンテンツをコンテンツプロバイダーに照会することで、検索を実行できます。 - 閲覧： ウォッチリスト、ビデオライブラリ、録画などをデバイスで閲覧できます。
- ページ分割： 検索結果の次のページに移動したり、画面の表示可能な領域を越えて検索結果をスクロールしたりすることができます。
- チャンネルナビゲーション： チャンネルのライブストリームまたは録画を再生できます。
- 検索結果からの再生： デバイスに表示されている検索結果からビデオを再生できます。再生は、音声を使用して行うことも、画面上のアイテムをタップして行うこともできます。
- おすすめ機能： 明示的にリクエストすることでおすすめを検索できます。
- ランディングページ： コンテンツのランディングページ（アプリのホーム画面に相当）に移動できます。Alexaには、ランディングページのテンプレートが用意されています（内容は開発者がレスポンスで設定します）。
Alexaから送信されるディレクティブ
サポートされている発話をユーザーが行うと、Alexaによってそれらの発話がディレクティブに変換され、Lambda関数に送信されます。閲覧、検索、チャンネル変更、クイック再生、おすすめなど、ユーザーが行う発話には、設定が異なるだけで、いずれもよく似たディレクティブが使用されます。
発話とシナリオは多様ですが、Lambdaから応答すべきディレクティブは、ほんの一握りしかありません。したがって、マルチモーダルデバイスを対象とするLambdaのコーディングは、次の表に示す6つのディレクティブの処理が中心となります。
| ディレクティブ | 説明 |
|---|---|
GetPlayableItems |
デバイスでビデオを再生するようユーザーがリクエストすると、このディレクティブがAlexaから送信されます。このディレクティブに含まれる条件に基づいてコンテンツを検索し、リクエストに対応するビデオのエンティティIDを返すことができます。Lambdaのレスポンスでは、ユーザーが定期購入により再生する権利を取得しているビデオがある場合は、それを優先する必要があります。リクエストに合致するビデオが見つからない場合は、適切なエラーレスポンスコードを返す必要があります。 |
GetPlayableItems（チャンネルナビゲーション） |
特定のチャンネルに切り替えるようユーザーがリクエストすると、このディレクティブがAlexaから送信されます。チャンネルが切り替わると、そのチャンネルのコンテンツが再生開始されます。 |
GetPlayableItemsMetadata |
Alexaは、直前のGetPlayableItemsで結果として返されたエンティティIDのセットについて、追加のメタデータを取得する目的でこのディレクティブを送信します。このメタデータには、ビデオを再生したりユーザーに適切なプロンプトを提供したりするうえで必要な情報が含まれます。 |
GetDisplayableItems |
ビデオを検索してその結果をデバイスに表示するようユーザーがリクエストすると、このディレクティブがAlexaから送信されます。このディレクティブに含まれる条件に基づいてコンテンツを検索し、検索リクエストに対応するビデオのエンティティIDを返すことができます。リクエストに合致するコンテンツが見つからない場合は、適切なエラーレスポンスを返す必要があります。 |
GetDisplayableItemsMetadata |
Alexaは、直前のGetDisplayableItemsで結果として返されたエンティティIDのセットについて、追加のメタデータを取得する目的でこのディレクティブを送信します。このメタデータには、AlexaがエンティティIDを検索結果としてデバイスに表示するうえで必要な情報が含まれています。 |
GetBrowseNodeItems |
Alexaは、検索結果内のグループ化されたコンテンツを取得する目的でこのディレクティブを送信します。マルチモーダルデバイスでは、複数のレイヤーを持つブラウズノードに検索結果をマージすることができます。グループ化された結果アイテムを選択してドリルダウンすることで、そのグループ内の結果をさらに表示することができます。GetBrowseNodeItemsディレクティブに対するLambdaのレスポンスでは、リクエストで指定されたグループに属するアイテムを返す必要があります。 |
GetNextPage |
ユーザーが画面をスクロールして現在表示されている結果の先を表示しようとすると、このディレクティブがAlexaから送信されます。このディレクティブは、画面に表示する結果のメタデータを取得した後、後続の結果を動的に取得する目的で呼び出されます。 |
想定されるLambdaのレスポンス
上記のディレクティブ（JSONメッセージ）をAlexaから受け取ったら、Lambdaはレスポンスとして、想定されるレスポンスフィールドとスキーマに準拠した、必要な情報（通常はコンテンツID）を提供するJSONメッセージを返す必要があります。下の図は、Alexaディレクティブとそれに対するLambdaのレスポンスを示しています。
Fire TV対応アプリのディレクティブとの比較
Fire TV対応アプリ用VSK（Video Skills Kit）の実装でも、Alexaから送信されるディレクティブを解釈して応答する必要があります（APIリファレンスの概要を参照）。このディレクティブは、マルチモーダルデバイスで使用されるディレクティブと似ていますが、以下のように違いがあります。
GetPlayableItems（マルチモーダルデバイス用）<–>SearchAndPlay（Fire TV対応アプリ用）：これらのディレクティブは再生の発話をサポートします。GetDisplayableItems（マルチモーダルデバイス用）<–>SearchAndDisplayResults（Fire TV対応アプリ用）：これらのディレクティブは検索の発話をサポートします。
ただし、マルチモーダルデバイスには、再生と検索という発話タイプごとに2つのディレクティブが用意されています（GetPlayableItemsとGetPlayableItemsMetadata、GetDisplayableItemsとGetDisplayableItemsMetadata）。これは、基本的な対話モデルが異なるためです。マルチモーダルデバイスでは、LambdaはレスポンスでAlexaに情報を返します。Fire TV対応アプリでは、LambdaはAmazon Device Messagingを通じて必要な情報を直接アプリにプッシュします。
用語 – リクエストとディレクティブ
「リクエスト」と「ディレクティブ」という用語は、このビデオスキルのドキュメントではほぼ同じ意味です。リクエストは、AlexaからLambdaに送信されるメッセージを指す、より一般的な用語です。ビデオスキルでは、メッセージはコード内でdirectiveとして記述されるため、リクエストを「ディレクティブ」と呼びます。 これは、その他のAlexa Skills Kitドキュメントで使用されている用語と一致しています。
また、この「ディレクティブ」という用語を使用することで、ユーザーの発話（映画を再生するリクエストなど）と、AlexaからLambdaに送信される情報とを区別することができます。
