開発者コンソール

GetPlayableItemsディレクティブ


GetPlayableItemsディレクティブ

VideoNameActorNameGenreNameなどの条件を使用して映画やテレビ番組、録画などを再生するようユーザーがAlexaに依頼すると、GetPlayableItemsディレクティブがVideoContentProvider APIからLambdaに送信されます。

下図のように、LambdaからはレスポンスとしてGetPlayableItemsResponseを返す必要があります。

GetPlayableItemsディレクティブとLambdaのGetPlayableItemsResponse

GetPlayableItemsの発話

ユーザーが以下の発話を行うと、AlexaはLambdaにGetPlayableItemsディレクティブを送信します。

機能 サンプル発話 想定されるレスポンス
タイトルを再生

Watch Breaking Bad

Spiele {title}

Öffne {title}

mets breaking bad

mets breaking bad

joue breaking bad

fai partire breaking bad

metti breaking bad

Pon la pelicula (title)

Pon breaking bad

Pon la pelicula (title)

Pon breaking bad

{title}を再生して

{title}を見せて

assistir {title}

ver {title}

{title} दिखाओ

{title} चलाओ

リクエストされたメディアが再生されます。一致するコンテンツが複数ある場合、ユーザーは目的のメディアを選択するように求められます。

メディアタイプで再生

Watch a movie

Spiele Filme

Spiele einen Film

mets un film

je veux voir un film

mets un film

joue un film

fai partire un film

metti un film

pon una película

(quiero) ver una película

pon una película

pon una peli

{media type}を再生して

{media type}を見せて

assistir filmes

ver filmes

एक {media type} चलाओ

एक {media type} चलाओ

タイトル以外のリクエストに一致するメディアが(ユーザーへのおすすめビデオを選び出すアルゴリズムによって)再生されるか、検索結果リストがユーザーに表示されます。

俳優で再生

Watch Sean Connery

Play a movie with Tom Hanks

spiele einen Film mit {actor} ab.

<Ann Blyth, Axel Deller, John Oliver>

mets un film de sean connery

je veux voir un film avec sean connery

mets un film de sean connery

mets un film avec sean connery

metti film con adriano celentano

fai partire un film con sean connery

pon (una película) de Sean Connery

(quiero) ver (una película) de Sean Connery

pon (una película) de Sean Connery

ponme (una película) de Sean Connery

{actor}を再生して

{actor}を見せて

assistir um filme com {actor/actress}

ver um filme com {actor/actress}

{actor}की movie चलाओ

{actor} की film लगा दो

俳優が出演しているメディアが(ユーザーへのベストマッチを選び出すアルゴリズムによって)再生されるか、検索結果リストがユーザーに表示されます。

シーズン番号で<タイトル>を再生

Watch breaking bad season two

Spiele {title} Staffel {X}

Spiele die {X}. Staffel von {title}

mets la saison 2 de breaking bad

mets la deuxième saison de breaking bad

mets la deuxième saison de breaking bad

joue la deuxième saison de breaking bad

metti la seconda stagione di breaking bad

fai partire la seconda stagione di breaking bad

Pon la temporada 2 de breaking bad

pon la segunda temporada de breaking bad

pon la temporada 2 de breaking bad

pon la segunda temporada de breaking bad

{title} シーズン{season number}を再生して

{title} シーズン{season number}を見せて

assistir {title} temporada {cardinal number}

ver {title} temporada {cardinal number}

{title} season two चलाओ

{title} season two चला दो

シリーズの最後に視聴したエピソードが視聴途中の場合は、そのエピソードが再生されます。視聴が完了している場合は、次の未視聴エピソードが再生されます。

エピソード番号で<タイトル>を再生

Watch breaking bad episode five

Spiele {title} Folge 5 ab.

<Breaking Bad>

mets l' épisode 5 de breaking bad

mets le cinquième épisode de breaking bad

mets le cinquième épisode de breaking bad

joue le cinquième épisode de breaking bad

metti il quinto episodio di breaking bad

fai partire il quinto episodio di breaking bad

pon el episodio 5 de breaking bad

pon el capítulo 5 de breaking bad

pon el episodio 5 de breaking bad

pon el capítulo 5 de breaking bad

{title} エピソード{episode number}を再生して

{title} エピソード{episode number}を見せて

assistir {title} episódio {cardinal number}

ver {title} number} episódio {cardinal number}

watch {title} episode five

play {title} episode five

ユーザーが最後に視聴したエピソードから、適切なシーズンが特定されます。シリーズの最後に視聴したエピソードが視聴途中の場合は、そのエピソードが再生されます。視聴が完了している場合は、次の未視聴エピソードが再生されます。

シーズン番号とエピソード番号で<タイトル>を再生

Watch breaking bad season two episode five

Spiele {title} Staffel 2 Folge 5 ab.

<Breaking Bad>

mets l' épisode 5 de la saison 2 de breaking bad

mets l' épisode 5 de la deuxième saison de breaking bad

mets l' épisode 5 de la saison 2 de breaking bad

mets l' épisode 5 de la deuxième saison de breaking bad

metti il quinto episodio della seconda stagione di breaking bad

fai partire il quinto episodio della seconda stagione di breaking bad

pon el episodio 5 de la temporada 2 de breaking bad

pon el episodio 5 de la segunda temporada de breaking bad

pon el episodio 5 de la temporada 2 de breaking bad

pon el episodio 5 de la segunda temporada de breaking bad

{title} シーズン{season number}エピソード{episode number}を再生して

{title} シーズン{season number}エピソード{episode number}を見せて

assistir {title} {ordinal number} temporada episódio {cardinal number}

ver {title} {ordinal number} temporada episódio {cardinal number}

play {title} season two episode five

{title} season two episode five लगाओ

リクエストされたシーズンとエピソードに対応するコンテンツが再生されます。

シリーズの<タイトル>で再生

Watch star trek

Spiele {franchise title}

Spiele {franchise title} Filme

mets star trek

je veux voir star trek

mets star trek

joue star trek

metti star trek

fai partire star trek

pon star trek

(quiero) ver star trek

pon star trek

pon una película de star trek

{franchise title}を再生して

{franchise title}を見せて

assistir {franchise title}

ver {franchise title}

{franchise title} चलाओ

watch {franchise title}

リクエストされたシリーズの検索結果から最上位のおすすめが再生されるか、一致するシリーズのリストがユーザーに表示されます。

キャラクター名で再生

Watch james bond

spiele einen Film mit {actor} ab.

<James Bond>

mets james bond

je veux voir james bond

mets james bond

mets un film de james bond

metti james bond

metti un film di james bond

pon james bond

(quiero) ver james bond

pon james bond

pon una película de james bond

{character}を再生して

{character}を見せて

assistir filmes com {character name}

ver filmes com {character name}

{character name} की picture चलाओ

{character name} की movie चलाओ

キャラクター名に一致するメディアが(ユーザーへのおすすめメディアを選び出すアルゴリズムによって)再生されるか、メディアの検索結果リストがユーザーに表示されます。

ジャンル名で再生

Watch comedy

einen (title) (film/serie) ansehen

mets un film policier

mets une émission sportive

mets film d' comédie

mets une comédie

metti una commedia

fam mi vedere una commedia

pon una comedia

(quiero) ver una comedia

pon una comedia

pon una película de comedia

{genre}を再生して

{genre}を見せて

assistir uma/um {genre name}

ver uma/um {genre name}

watch {genre name}

play {genre name}

リクエストされたジャンルからメディアが(ユーザーへのおすすめメディアを選び出すアルゴリズムによって)再生されるか、メディアの検索結果リストがユーザーに表示されます。

スポーツのチームで再生

Watch seahawks

Zeig mir {sports team}

Zeig mir das Spiel von {sports team}

mets les bleus

je veux voir les bleus

mets les canadiens

mets le match des canadiens

fam mi vedere la Juventus

<Aberdeen, ac milan>

pon el Madrid

(quiero) ver el Madrid

pon el América

pon el partido del América

{sports team}を再生して

{sports team}を見せて

assistir {sports team}

ver {sports team}

{sports team} चलाओ

{sports team} की game चलाओ

スポーツのチームに一致するメディアが(ユーザーへのおすすめメディアを選び出すアルゴリズムによって)再生されるか、メディアの検索結果リストがユーザーに表示されます。

スポーツの種類で再生

Watch soccer

Zeig mir {sports type}

{sports type} anschauen

mets du foot

je veux voir du foot

mets du hockey

mets le hockey

fam mi vedere una partita di calcio

metti la/una partita

pon el fútbol

(quiero) ver el fútbol

pon fútbol

ponme fútbol

{sports type}を再生して

{sports type}を見せて

assistir {sports type}

ver {sports type}

watch {sports type}

{sports type} चलाओ

スポーツの種類に一致するメディアが(ユーザーへのおすすめメディアを選び出すアルゴリズムによって)再生されるか、検索結果リストがユーザーに表示されます。

スポーツのリーグで再生

Watch n. b. a. league

Zeig mir die {sports league}

{sports league} anschauen

Mets la n.b.a.

Je veux voir la n.b.a.

mets la l. n. h.

je veux regarder la l. n. h.

fam mi vedere la n.b.a.

metti l'n.b.a.

pon la n. b. a.

(quiero) ver la n. b. a.

pon la n. b. a.

ponme la n. b. a.

{sports league}を再生して

{sports league}を見せて

assistir {sports league}

ver {sports league}

watch {sports league}

{sports league} चलाओ

スポーツのリーグに一致するメディアが(ユーザーへのおすすめメディアを選び出すアルゴリズムによって)再生されるか、検索結果リストがユーザーに表示されます。

スポーツのイベントで再生

Watch soccer game

Zeig mir das {sports event}

Zeig mir ein {sports event}

mets un match de foot/football

je veux voir un match de foot/football

mets une partie de hockey

je veux regarder une partie de hockey

metti una partita di calcio

fam mi vedere una/la partita

pon el partido de fútbol

(quiero) ver el partido de fútbol

pon el partido de fútbol

ponme el partido de fútbol

{sports event}を再生して

{sports event}を見せて

assistir {sports event}

ver {sports event}

watch {sports event}

play {sports event}

スポーツのイベントに一致するメディアが(ユーザーへのおすすめメディアを選び出すアルゴリズムによって)再生されるか、検索結果リストがユーザーに表示されます。

GetPlayableItemsディレクティブの処理

Alexaは、ユーザーの発話を解析してインテントを判断し、それをGetPlayableItemsディレクティブとしてパッケージ化します。しかし、ユーザーが何を再生したいのかがはっきりとはわからない場合もあります。そこでAlexaは、再生するアイテムを検索できるよう、リクエストされたコンテンツをLambdaに送信します。

Lambdaから送信するレスポンスには、再生可能なコンテンツを特定する基本的な情報を含める必要があります。そのレスポンスに応じて、Alexaは次のことを行います。

  • Lambdaからレスポンスで返されたアイテムが1つだけの場合は、再生を開始するためにGetPlayableItemsMetadataディレクティブを送信します。
  • Lambdaからレスポンスで返されたアイテムが複数ある場合は、検索結果を表示するためにGetDisplayableItemsMetadataディレクティブを送信します。

GetPlayableItemsディレクティブは、header名を除けばGetDisplayableItemsと同じです。GetPlayableItemsディレクティブが使用されるのは、デバイスでコンテンツを再生するようユーザーから依頼された場合です。再生用のディレクティブと検索用のディレクティブとが分かれているため、よりユーザーのインテントに沿った処理を行うことが可能になります。 

各種のシナリオで検索を実行する方法についての一般的な指針は次のとおりです。

ビデオ名 (例:「『インターステラー』を再生して」)

「『インターステラー』を再生して」のように、ユーザーの発話にビデオ名が含まれていた場合、Alexaから送信されるGetPlayableItemsディレクティブには、カタログ内で見つかった関連性の高いビデオ名がすべて含まれます。また、このディレクティブのexternalIdsフィールドには、カタログIDも含まれています。videoNamesと共に送信されるIDに基づいてコンテンツを選定し、再生できるアイテムを選択して返すようにしてください。

ジャンル/俳優 (例:「コメディ映画を再生して」、「トム・クルーズのアクション映画を再生して」)

ビデオ名がなく、ジャンルや俳優といったその他のスロットがある場合は、GetPlayableItemsディレクティブがAlexaから送信されます。このような場合は、ディレクティブで送信されたエンティティを使用して検索を実行する必要があります。

たとえば、「アクション映画を再生して」という発話の場合、{mediaType: MOVIE, genreName: コメディ}GetPlayableItemsディレクティブで送信されます。この情報を基に検索を実行し、コメディ映画の識別子を返すことができます。 

「トム・クルーズのアクション映画を再生して」という発話の場合も同様に、{mediaType: MOVIE, genreName: アクション, actorName: トム・クルーズ}GetPlayableItemsディレクティブで送信されるので、この条件に一致する映画の識別子を検索して返すことができます。

識別子をレスポンスで返すと、追加のメタデータを取得するためのGetPlayableItemsMetadataディレクティブがAlexaから送信されます。

GetPlayableItemsの例

GetPlayableItemsディレクティブの例を次に示します。この例では、メディアのタイトル(「マンチェスター・バイ・ザ・シー」)がユーザーから明示的に指定されています。

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetPlayableItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "entities": [
                {
                    "type": "Video",
                    "value": "マンチェスター・バイ・ザ・シー",
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    }
                }
            ],
            "contentType": "RECORDING",
            "locale": "ja-JP",
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}

ペイロードの説明

次の表は、GetPlayableItemsディレクティブのpayloadについて説明しています。

ペイロードの説明
フィールド 説明 データ型
entities
(必須)

検索するエンティティオブジェクトのリスト。通常、異なるエンティティタイプ間の関係は、AND演算と解釈されます。たとえば、{genreName = "コメディ," actorName ="トム・ハンクス"}を含むリクエストの場合、検索結果にはトム・ハンクスが出演するコメディの映画またはテレビ番組が含まれる必要があることになります。

一方、{videoName = "インターステラー," VideoName = "宇宙戦争"}など、同じタイプの複数のエンティティがリクエストに含まれる場合は、OR演算と見なし、ディレクティブ内のすべてのエンティティを検索することができます。不確かな場合は、そのタイプ(このケースではvideoName)の先頭のエンティティを最も関連性が高いものと見なします。

さらに、{mediaType = "MOVIE', genreName = "コメディ," actorName ="トム・ハンクス," actorName = "トム・ハンクス}というリクエストを考えてみましょう。これは、トム・ハンクスという名前の俳優が複数存在すると考えられます。このような場合は、リクエスト内のすべての俳優を含む映画を検索したうえで、コメディのジャンルでフィルタリングして、すべての検索結果を返すことができます。

現時点では、一致するエンティティが複数ある場合にユーザーが何を再生したいかを知る方法がAlexaにはないため、エンティティのランク付けは行われません。

type: Channelを持つentitiesには、 テレビチャンネルの識別データが格納されます。以下に例を示します。

 {
  "type": "Channel",
  "value": "PBS",
  "externalIds": {
      "gracenote": "MV000000099001"
  },
  "entityMetadata": {
      "channelCallSign": "KBTC",
      "channelNumber": "123"
  }
} 

リスト
type

ビデオコンテンツのエンティティタイプ。ビデオコンテンツのエンティティタイプの詳細については、ビデオコンテンツのエンティティタイプを参照してください。このリストに加えて、Alexa Skills Kitには、マルチモーダルデバイス用の新しいタイプ (LISTTYPESORTTYPE)が追加されています。

LISTTYPEは、ユーザーがウォッチリストやライブラリの閲覧を希望した場合に設定されます。たとえば、「ウォッチリストを見せて」や「ビデオライブラリを見せて」といった発話が挙げられます。 LISTTYPEには、次の列挙値を設定できます。

  • WATCHLIST: 「ウォッチリストを見せて」 - ユーザーのウォッチリストに追加されているビデオを表示する際に使用します。
  • LIBRARY: 「ビデオライブラリを見せて」 - ユーザーのライブラリに存在するビデオを表示する際に使用します。通常、これにはユーザーが購入したビデオが該当します。

SORTTYPEは、検索時に使用するリクエストの追加情報や、結果のソート方法を指定する際に使用します。たとえば、「おすすめの映画を見せて」という発話の場合、Alexaはコンテンツプロバイダーからのおすすめコンテンツを取得する必要があります。SORTTYPEには、次の列挙値を設定できます。

  • RECOMMENDED: 「おすすめの映画を見せて」や「おすすめのアクション映画を見せて」といった発話の場合、この値が設定されます。

例: MEDIATYPEVIDEOACTORGENREFRANCHISESEASONEPISODE

文字列
value
(必須)

エンティティの値。チャンネルの場合は、チャンネル名。

例: インターステラーPBS

文字列
externalIds

このエンティティの外部識別子のマップ。keyはプロバイダー、valueidです。

例:key = gracenote(またはgti)、value = SH000000012

オブジェクト
Gracenote

外部Gracenote ID。

例: ST0000000666661

文字列
contentType

contentTypeは、検索するコンテンツのカテゴリーを指定します。エンティティのmediaTypeとは異なることに注意してください。mediaTypeでは、検索するメディアのタイプ(映画、テレビ番組など)を指定します。そのため、録画した映画を閲覧する場合は、「録画した映画を見せて」などと発話します。このとき、mediaTypeはMOVIEに、contentTypeはRECORDINGに設定されます。同様に、ライブTVのコンテンツを閲覧する場合は、「今放送中の番組を見せて」などと発話します。このとき、contentTypeはLIVEに設定されます。

例: RECORDINGLIVEON_DEMAND

列挙型
locale
(必須)

ユーザーのロケール。検索結果に対応する表示可能な情報を取得するために必要となります。ロケールの形式は、Network Working Groupの「Best Current Practice 47(BCP-47)」(英語のみ)で規定されている言語の形式と同じです。認識されないロケールを受信した場合は、デフォルトでen-USになります。

例:en-USen-GBde-DE

文字列
minResultLimit
(必須)

この呼び出しで返される結果でpageTokenが必要となる最小件数。pageTokenと共に返されたアイテムの件数がminResultLimitフィールドよりも少ない場合、Alexaは新しいアイテムを取得せずに、受信したアイテムをそのまま表示します。pageTokenは次の結果を取得する際に必要となるため、この場合は使用されません。

pageTokenを使用して次の結果を取得するのは、アイテムの件数がminResultLimitの値以上である場合のみです。ただし、アイテムの件数がminResultLimitを超える場合は、maxResultLimitが上限となります。アイテムの件数がmaxResultLimitを超えると、maxResultLimitを超えたアイテムはAlexaによって破棄されます。

例: 8

整数
maxResultLimit
(必須)

返される結果の最大件数(上限)。詳細については、minResultLimitフィールドの説明を参照してください。

例: 25

整数
timeWindow

リクエストされた処理の開始時刻と終了時刻を指定します。これは通常、ライブTVや録画にのみ使用され、オンデマンドコンテンツには使用されません。一般的に、タイムウィンドウが指定されており、それを使用して結果をフィルタリングできる場合は、タイムウィンドウを使用する必要があります。

検索対象がオンデマンドコンテンツのみとなるプロバイダーの場合は、タイムウィンドウフィールドが通常nullに設定されているため、無視して構いません。

ライブTVや録画でユーザーがタイムウィンドウを指定している場合(「午後4時から5時のテレビ番組を検索して」や「先週録画したテレビ番組を探して」など)、開始時刻と終了時刻が指定されていれば、それらを使用して結果をフィルタリングする必要があります。

機能によって、startendの両方のフィールドが存在する場合と、どちらか一方のフィールドしか存在しない場合とがあります。たとえば、「午後4時から5時のテレビ番組を検索して」の場合は両方のフィールドが存在しますが、「午後5時に始まるテレビ番組を見せて」の場合、設定されるのはstartフィールドだけで、endフィールドはnullになります。

startendの時間を含むオブジェクト
start

タイムウィンドウの開始時刻。

例: 2016-09-07T23:59:00+00:002018-01-24T02:30:00Z

ISO 8601形式の文字列
end

タイムウィンドウの終了時刻。

例: 2016-09-07T23:59:00+00:002018-01-24T02:30:00Z

ISO 8601形式の文字列

Lambdaのレスポンス

GetPlayableItemsディレクティブを受信したら、Lambdaはここで示す構造に準拠したGetPlayableItemsResponseレスポンスを返す必要があります。この場合のレスポンス構造は、GetDisplayableItemsディレクティブに対して返すレスポンスと同様です。

レスポンスについては、以下のガイドラインに従ってください。 

  • GetPlayableItemsディレクティブの目的は、そのディレクティブで再生できる単一のアイテムを取得することです。 

  • 再生するアイテムが1つしかない場合、そのアイテムを返せば、Alexaによってアイテムが再生されます。 

  • 再生するアイテムがはっきりしない場合は、レスポンスで複数のアイテムを返すことができます。Alexaは、その中から再生するアイテムを選択するようユーザーに促します。たとえば、ユーザーが「『スター・ウォーズ』を再生して」と言った場合、レスポンスで返すアイテムとしては、「スター・ウォーズ」シリーズの映画だけでなく、「スター・ウォーズ」に関連したさまざまな映画やテレビ番組が考えられます。複数の結果を返した場合、Alexaはメタデータを取得して検索結果を表示するためにGetDisplayableItemsMetadataディレクティブを送信します。1回目の呼び出しで返す結果の件数が、ディレクティブで指定されたresultLimitパラメーターの値を超えないように注意してください。

  • ユーザーにタイトルを再生する権限がないことや、定期購入が必要であることが原因で、見つかった唯一の結果が再生できない場合でも、そのアイテムを返すことができます。そのアイテムが再生できないとわかると、Alexaはメタデータを取得して、購入・レンタル・定期購入を促すプロンプトを提供します。その後、ユーザーは購入ワークフローを開始し、タイトルを購入・レンタルしてから再生することができます。

  • 再生できない結果が複数見つかった場合は、その結果をすべて返すことができます。Alexaは、再生するアイテムを選び出すようユーザーに求めるか、アイテムの購入・レンタル・定期購入を促すプロンプトを提供します。

  • 再生できるアイテムと再生できないアイテムとが混在する複数の結果が見つかった場合は、再生できるアイテムを優先する必要があります。デバイスで再生できるように、再生可能な結果を返すようにしてください。

レスポンスの例

GetPlayableItemsに対するLambdaからのレスポンスの例を次に示します。

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetPlayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}

ペイロードの説明

次の表は、GetPlayableItemsResponsepayloadフィールドについて説明しています。

ペイロードの説明
フィールド 説明 データ型
nextToken

次の結果セットを取得するためのトークン。プロバイダーから送信される不透明型の文字列で、後続の検索リクエストで返されます。

文字列
mediaItems
(必須)

検索結果として画面に表示されるビデオのmediaIdentifiersのリスト。

リスト
mediaIdentifier
(必須)

mediaItemの識別子。mediaIdentifierオブジェクトからの画像サイズデータの取得を参照してください。

オブジェクト
id
(必須)

ビデオアイテムの識別子。後続のGetDisplayableItemsMetadataまたはGetPlayableItemsMetadataの呼び出しで、表示または再生に関連したメタデータ情報を取得する目的で使用されます。この識別子は、Alexaからは認識できず、メタデータ情報を照会する際にそのまま使用されます。

文字列