開発者コンソール

APIリファレンスの概要


APIリファレンスの概要

ビデオスキルのディレクティブは、AlexaからLambda関数に送信されます。ディレクティブは、特定のアクション(ビデオのメタデータの取得など)の実行に関する命令を含むJSONメッセージであり、名前とペイロードが異なるさまざまなディレクティブが存在します。Lambda関数は、受信したディレクティブを処理して、所定のJSON形式に準拠したレスポンスを返す必要があります。一般的には、Alexaから送信される「ディレクティブ」と呼ばれるリクエスト(JSON形式)と、Lambdaから送信されるレスポンス(同じくJSON形式)が基本モデルとなります。つまり、JSON形式でリクエストを受け取り、JSON形式でレスポンスを返します。

マルチモーダルデバイスでサポートされる発話

概要で説明されているように、マルチモーダルデバイスでは以下の発話がサポートされています。

検索

VideoNameActorNameGenreNameなどの条件を使用して、表示するコンテンツをコンテンツプロバイダーに照会することで、検索を実行できます。次のような発話が考えられます。

  • "Search for movies with Tom Hanks."
  • "Find 'The Big Bang Theory.'"
  • "Find 'The Big Bang Theory' Season 1 episode 4."
  • "Search for Interstellar."
  • "Search for comedy movies."
  • "Search comedy movies with Tom Hanks."
  • "Suche Filme mit Tom Hanks."
  • "Finde The Big Bang Theory."
  • "Finde The Big Bang Theory Staffel 1 Folge 4."
  • "Suche Interstellar."
  • "Suche Filmkomödien."
  • "Suche Filmkomödien mit Tom Hanks."
  • "Recherche des films avec Tom Hanks."
  • "Trouve The Big Bang Theory."
  • "Trouve The Big Bang Theory, saison 1, épisode 4."
  • "Recherche Insterstellar."
  • "Recherche des comédies."
  • "Recherche des comédies avec Tom Hanks."
  • "Cerca film con Tom Hanks."
  • "Cerca The Big Band Theory."
  • "Cerca The Big Band Theory stagione 1 episodio 4."
  • "Cerca Interstellar."
  • "Cerca commedie."
  • "Cerca commedie con Tom Hanks."
  • "Busca películas de Tom Hanks."
  • "Busca The Big Bang Theory."
  • "Busca el episodio 4 de la temporada 1 de The Big Bang Theory."
  • "Busca Interstellar."
  • "Busca películas de comedia."
  • "Busca comedias con Tom Hanks."
  • "Busca películas de Tom Hanks."
  • "Busca The Big Bang Theory."
  • "Busca el episodio 4 de la temporada 1 de The Big Bang Theory."
  • "Busca Interstellar."
  • "Busca películas de comedia."
  • "Busca comedias con Tom Hanks."
  • 「トム・ハンクスの映画を検索して」
  • 「『ビッグバン・セオリー』を探して」
  • 「『ビッグバン・セオリー』のシーズン1のエピソード4を探して」
  • 「『インターステラー』を検索して」
  • 「コメディ映画を検索して」
  • 「トム・ハンクスのコメディ映画を検索して」
  • "Procure filmes com Tom Hanks."
  • "Procure por The Big Bang Theory."
  • "Procure pelo quarto episódio da primeira temporada de The Big Bang Theory."
  • "Procure por Interstellar."
  • "Procure por filmes de comédia."
  • "Procure por filmes de comédia com Tom Hanks."
  • "Tom Hanks की फ़ि‍ल्में सर्च करो."
  • "'The Big Bang Theory' ढूंढो."
  • "'The Big Bang Theory' सीज़न 1 एपिसोड 4 ढूंढो."
  • "Interstellar सर्च करो."
  • "कॉमेडी मूवीज़ सर्च करो."
  • "Tom Hanks की कॉमेडी मूवीज़ सर्च करो."

閲覧

ウォッチリスト、ビデオライブラリ、録画などをデバイスで閲覧できます。次のような発話が考えられます。

  • "Show me my video library."
  • "Show me my watch list."
  • "Show me my recordings."
  • "Zeig meine Videothek an."
  • "Zeig meine Watchlist an."
  • "Zeig meine Aufzeichnungen an."
  • "Montre-moi ma bibliothèque vidéo."
  • "Montre-moi ma liste de favoris."
  • "Montre-moi mes enregistrements."
  • "Mostrami la mia libreria video."
  • "Mostrami la mia watch list."
  • "Mostrami le mie registrazioni."
  • "Muéstrame mi biblioteca de vídeo."
  • "Enséñame la lista de seguimiento."
  • "Enséñame mis grabaciones."
  • "Muéstrame mi biblioteca de vídeo."
  • "Enséñame la lista de seguimiento."
  • "Enséñame mis grabaciones."
  • 「ビデオライブラリを見せて」
  • 「ウォッチリストを見せて」
  • 「録画したビデオを見せて」
  • "Mostre-me a minha biblioteca de vídeo."
  • "Mostre-me a minha lista de itens a assistir."
  • "Mostre-me as minhas gravações."
  • "मुझे मेरी वीडियो लाइब्रेरी दिखाओ."
  • "मुझे मेरी वॉचलिस्ट दिखाओ."
  • "मुझे मेरी रिकॉर्डिंग्स दिखाओ."

ページ分割

検索結果の次のページに移動したり、画面の表示可能な領域を越えて検索結果をスクロールしたりすることができます。発話の例を次に示します。

  • "Next page"

クイック再生

VideoNameActorNameGenreNameなどの条件を使用して、デバイスで再生するコンテンツをコンテンツプロバイダーに照会することで、映画、テレビ番組、録画などを検索できます。その後、(検索結果などを表示することなく)直接そのコンテンツを再生することができます。次のような発話が考えられます。

  • "Play a movie with Tom Hanks."
  • "Play Interstellar." 
  • "Play a comedy movie."
  • "Play 'The Big Bang Theory'."
  • "Play 'The Big Bang Theory' Season 1, episode 6."
  • "Play a movie." 
  • "Spiel einen Film mit Tom Hanks."
  • "Spiel Interstellar."
  • "Spiel eine Filmkomödie."
  • "Spiel The Big Bang Theory."
  • "Spiel The Big Bang Theory Staffel 1 Folge 6."
  • "Spiel einen Film."
  • "Mets un film avec Tom Hanks."
  • "Mets Interstellar."
  • "Mets une comédie."
  • "Mets The Big Bang Theory."
  • "Mets The Big Bang Theory, saison 1, épisode 6."
  • "Mets un film."
  • "Riproduci un film con Tom Hanks."
  • "Riproduci Interstellar."
  • "Riproduci una commedia."
  • "Riproduci The Big Band Theory."
  • "Riproduci The Big Band Theory stagione 1 episodio 6."
  • "Riproduci un film."
  • "Pon una película de Tom Hanks."
  • "Pon Interstellar."
  • "Pon una película de comedia."
  • "Pon The Big Bang Theory."
  • "Pon el episodio 6 de la temporada 1 de The Big Bang Theory."
  • "Pon una película."
  • "Pon una película de Tom Hanks."
  • "Pon Interstellar."
  • "Pon una película de comedia."
  • "Pon The Big Bang Theory."
  • "Pon el episodio 6 de la temporada 1 de The Big Bang Theory."
  • "Pon una película."
  • 「トム・ハンクスの映画を再生して」
  • 「『インターステラー』を再生して」
  • 「コメディ映画を再生して」
  • 「『ビッグバン・セオリー』を再生して」
  • 「『ビッグバン・セオリー』のシーズン1のエピソード6を再生して」
  • 「映画を再生して」
  • "Coloque um filme com Tom Hanks."
  • "Coloque Interstellar."
  • "Coloque um filme de comédia.
  • "Coloque The Big Bang Theory."
  • "Coloque o sexto episódio da primeira temporada de The Big Bang Theory."
  • "Coloque um filme."
  • "Tom Hanks की मूवी चलाओ."
  • "Interstellar चलाओ."
  • "कॉमेडी मूवी चलाओ."
  • "'The Big Bang Theory' चलाओ."
  • "'The Big Bang Theory' सीज़न 1, एपिसोड 6 चलाओ."
  • "एक मूवी चलाओ."

チャンネルナビゲーション

チャンネルのライブストリームまたは録画を再生できます。次のような発話が考えられます。

  • "Tune to CNN."
  • "Tune to ESPN."
  • "Gehe zu CNN."
  • "Gehe zu ESPN."
  • "Mets CNN."
  • "Mets ESPN."
  • "Metti RAI 1."
  • "Metti RAI Sport."
  • "Pon Televisión Española."
  • "Pon Antena 3."
  • "Pon Televisa."
  • "Pon TV Azteca."
  • 「CNNをつけて」
  • 「ESPNをつけて」
  • "Coloque na CNN."
  • "Coloque na ESPN."
  • "CNN पर ट्यून करो."
  • "ESPN पर ट्यून करो."

検索結果からの再生

デバイスに表示されている検索結果からビデオを再生できます。再生は、音声を使用して行うことも、画面上のアイテムをタップして行うこともできます。次のような発話が考えられます。

  • "Play number 1."
  • "Play the second one."
  • "Select number 1."
  • "Select the second one."
  • "Spiel Nummer 1."
  • "Spiel den zweiten."
  • "Wähle Nummer 1."
  • "Wähle den zweiten."
  • "Mets le numéro 1."
  • "Mets le deuxième."
  • "Sélectionne le numéro 1."
  • "Sélectionne le second."
  • "Riproduci il numero 1."
  • "Riproduci il secondo."
  • "Seleziona il numero 1."
  • "Seleziona il secondo."
  • "Pon el número 1."
  • "Pon el segundo."
  • "Selecciona el número 1."
  • "Selecciona el segundo."
  • "Pon el número 1."
  • "Pon el segundo."
  • "Selecciona el número 1."
  • "Selecciona el segundo."
  • 「1番を再生して」
  • 「2番目のを再生して」
  • 「1番を再生して選択」
  • 「2番目のを選択」
  • "Coloque no número 1."
  • "Coloque no segundo."
  • "Selecione o número 1."
  • "Selecione o segundo."
  • "नंबर 1 चलाओ."
  • "दूसरा चलाओ."
  • "नंबर 1 चुनो."
  • "दूसरा चुनो."

おすすめ

明示的にリクエストすることでおすすめを検索できます。次のような発話が考えられます。

  • "Show me recommended movies"
  • "Open Amazon Video"
  • "Zeig mir Filmempfehlungen"
  • "Öffne Amazon Video"
  • "Montre-moi des films recommandés."
  • "Ouvre Amazon Video."
  • "Mostrami il film consigliati."
  • "Apri Prime Video."
  • "Enséñame películas recomendadas."
  • "Abre Prime Video."
  • "Enséñame películas recomendadas."
  • "Abre Prime Video."
  • 「おすすめの映画を見せて」
  • 「Amazonプライム・ビデオを開いて」
  • "Mostre-me recomendações de filmes."
  • "Abra o Amazon Video."
  • "मुझे सुझाई गई फ़ि‍ल्में दिखाओ."
  • "Amazon वीडियो खोलो."

「Amazonプライム・ビデオを開いて」という発話は、おすすめの検索に変換されます。

ランディングページ

コンテンツのランディングページ(アプリのホーム画面に相当)に移動できます。Alexaには、ランディングページのテンプレートが用意されています(内容は開発者がレスポンスで設定します)。次のような発話が考えられます。

  • "Open your app name."
  • "Öffne App-Name"
  • "Ouvre ton application."
  • "Apri your app name"
  • "Abre your app name."
  • "Abre your app name."
  • 「<アプリ名>を開いて」
  • "Abra o seu aplicativo app name."
  • "अपना ऐप नाम खोलो."

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のレスポンスを示しています。

GetPlayableItemsディレクティブとLambdaのGetPlayableItemsResponse
GetPlayableItemsMetadataItemsディレクティブとLambdaのGetPlayableItemsMetadataResponse
GetDisplayableItemsディレクティブとLambdaのGetDisplayableItemsResponse
GetDisplayableItemsMetadataディレクティブとLambdaのGetDisplayableItemsMetadataResponse
GetBrowseNodeItemsディレクティブとLambdaのGetBrowseNodeItemsResponse
GetNextPageディレクティブとLambdaのGetNextPageResponse

Fire TV対応アプリのディレクティブとの比較

Fire TV対応アプリ用VSK(Video Skills Kit)の実装でも、Alexaから送信されるディレクティブを解釈して応答する必要があります(APIリファレンスの概要を参照)。このディレクティブは、マルチモーダルデバイスで使用されるディレクティブと似ていますが、以下のように違いがあります。

  • GetPlayableItems(マルチモーダルデバイス用)<–> SearchAndPlay(Fire TV対応アプリ用):これらのディレクティブは再生の発話をサポートします。
  • GetDisplayableItems(マルチモーダルデバイス用)<–> SearchAndDisplayResults(Fire TV対応アプリ用):これらのディレクティブは検索の発話をサポートします。

ただし、マルチモーダルデバイスには、再生と検索というそれぞれのタイプの発話に対して2つのディレクティブが用意されています(GetPlayableItemsGetPlayableItemsMetadataGetDisplayableItemsGetDisplayableItemsMetadata)。これは、基本的な対話モデルが異なるためです。マルチモーダルデバイスでは、LambdaはレスポンスでAlexaに情報を返します。Fire TV対応アプリでは、LambdaはAmazon Device Messagingを通じて必要な情報を直接アプリにプッシュします。

用語 – リクエストとディレクティブ

「リクエスト」と「ディレクティブ」という用語は、このビデオスキルのドキュメントではほぼ同じ意味です。リクエストは、AlexaからLambdaに送信されるメッセージを指す、より一般的な用語です。ビデオスキルでは、メッセージはdirectiveとして記述されるため、コード内ではリクエストを「ディレクティブ」と呼びます。 これは、その他のAlexa Skills Kitドキュメントで使用されている用語と一致しています。

また、この「ディレクティブ」という用語を使用することで、ユーザーの発話(映画を再生するリクエストなど)と、AlexaからLambdaに送信される情報とを区別することができます。