チャンネルナビゲーション用のGetPlayableItemsディレクティブ


チャンネルナビゲーション用のGetPlayableItemsディレクティブ

チャンネルを変更するための発話をユーザーが行うと(「PBSを見せて」など)、表示するチャンネルについての情報と共に、GetPlayableItemsディレクティブがVideoContentProvider APIからLambdaに送信されます。

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

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

GetPlayableItemsの発話(チャンネルナビゲーション)

ユーザーが以下のチャンネル変更の発話を行うと、AlexaからLambdaにGetPlayableItemsディレクティブが送信されます。これは通常のGetPlayableItemsディレクティブとほぼ同じですが、チャンネル固有のプロパティが含まれます。

機能 サンプル発話 想定される結果
チャンネル名に移動

Go to Fox

Tune to ESPN

Schalte auf <channel>

Wechsel zu <channel>

Umschalten auf <channel>

Gehe zu <channel name>

<Sat Eins Emotions, Kabel Eins Doku, radio SAW>

Mets Fox

Va sur Fox

change à radio-canada

mets radio-canada

va à/sur radio-canada

joue radio-canada

passe à radio-canada

vai sulla Fox

cambia sulla Fox

metti la Fox

<alfa>

cambia a Fox

ve a Fox

abre Fox

cambia a t.v. Azteca

cámbiale a t.v. Azteca

cámbia le a t.v. Azteca

ve a t.v. Azteca

abre t.v. Azteca

{channel} 見せて

{channel} 開いて

{channel} に行って

{channel} をお願い

{channel} 選んで

{channel} を選択して

ビューがチャンネル名に切り替わり、チャンネルのコンテンツが再生されます。

チャンネル番号に移動

Go to channel thirteen

Schalte auf <channel number>

Schalte auf Kanal/Sender <channel number>

Umschalten auf <channel number>

Mets la 5

Passe sur la 5

Va sur la 5

change au (poste) 10

mets le (poste) 10

va au/sur le (poste) 10

joue le (poste) 10

passe au (poste) 10

change au (canal) 10

mets le (canal) 10

va au/sur le (canal) 10

joue le (canal) 10

passe au (canal) 10

change à la chaîne 10

mets la chaîne 10

va à/sur la chaîne 10

joue la chaîne 10

passe à la chaîne 10

vai al canale 13

cambia sul canale 13

metti il canale 13

ve al canal 13

cambia al canal 13

ve al canal 13

cambia al canal 13

vete al canal 13

cámbiale al canal 13

cámbia le al canal 13

チャンネル {channel number} 開いて

チャンネル {channel number} に行って

チャンネル {channel number} をお願い

チャンネル {channel number} 選んで

チャンネル {channel number} 選択して

{channel number} チャンネル 開いて

{channel number} チャンネル に行って

{channel number} チャンネル をお願い

{channel number} チャンネル 選んで

{channel number} チャンネル を選択して

ビューがチャンネル番号に切り替わり、チャンネルのコンテンツが再生されます。

チャンネルコールサインに移動

Go to channel k. c. p. q.

Schalte auf <channel callsign>

Umschalten auf <channel callsign>

Mets la chaîne (channel code)

Passe sur la chaîne (channel code)

Va sur la chaîne (channel code)

change au ( canal ) (channel code)

mets le ( canal ) (channel code)

va au/sur le canal (channel code)

joue le canal (channel code)

change au poste (channel code)

mets le poste (channel code)

va/sur le au poste (channel code)

joue le poste (canal) channel code)

change à la chaîne (channel code)

mets la chaîne (channel code)

va à/sur la chaîne (channel code)

joue la chaîne (channel code)

vai al canale (code)

cambia sul canale (code)

metti il canale (code)

cambia al canal (channel code)

ve al canal (channel code)

cambia al canal (channel code)

ve al canal (channel code)

cámbiale al canal (channel code)

vete al canal (channel code)

cámbia e al canal (channel code)

vete al canal (channel code)

チャンネル {channel callsign} 見せて

チャンネル {channel callsign} 開いて

チャンネル {channel callsign} に行って

チャンネル {channel callsign} をお願い

チャンネル {channel callsign} を選んで

チャンネル {channel callsign} を選択して

ビューがチャンネルコールサインに切り替わり、チャンネルのコンテンツが再生されます。

チャンネル名を視聴

Watch fox

Zeige <channel name>

<channel name> anschauen

Spiel <channe name> ab

<Sat Eins Emotions, Kabel Eins Doku, radio SAW>

Mets Fox

Je veux voir/regarder Fox

Va sur Fox

Passe à Fox

mets radio-canada

va à/sur radio-canada

joue radio-canada

Je veux écouter/regarder/voir radio-canada

vai sulla Fox

cambia sulla Fox

metti la Fox

<alfa>

pon Fox

(quiero) ver Fox

pon t.v. Azteca

ponme t.v. Azteca

pon me t.v. Azteca

(quiero) ver t.v. Azteca

{channel name}を再生して

{channel name}を見せて

{channel name}を流して

{channel name}をかけて

{channel name}見たい

{channel name}をお願い

ビューがチャンネル名に切り替わり、チャンネルのコンテンツが再生されます。

チャンネル番号を視聴

Watch channel thirteen

Zeige Kanal/Sender <channel number>

Kanal/Sender <channel number> anschauen

Mets la 5

Je veux voir/regarder la 5

mets le (canal) 10

va au/sur le

joue le (canal) 10

Je veux écouter/regarder/voir le (canal) 10

vai al canale 13

cambia sul canale 13

metti il canale 13

pon el canal 13

(quiero) ver el canal 13

pon el canal 13

(quiero) ver el canal 13

ponme el canal 13

チャンネル {channel number} 見せて

{channel number} チャンネル 見せて

ビューがチャンネル番号に切り替わり、チャンネルのコンテンツが再生されます。

チャンネルに関しては、マルチモーダルデバイスとFire TV対応アプリとで実装が異なることに注意してください。Fire TV対応アプリではチャンネルナビゲーション専用のディレクティブ(ChannelChange)があるのに対し、マルチモーダルの実装では、再生とチャンネルナビゲーションのどちらの発話にもGetPlayableItemsを使用します(ただしプロパティは異なります)。

GetPlayableItemsの例(チャンネルナビゲーション)

特定のチャンネルのGetPlayableItemsディレクティブの例を次に示します。payloadには、チャンネルのシナリオに固有のフィールドが存在します。

{
    "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": "Channel",
                    "value": "PBS",
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    },
                    "entityMetadata": {
                        "channelCallSign": "KBTC",
                        "channelNumber": "123"
                    }
                }
            ],
            "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"
            }
        }
    }
}

"type": "Channel"を持つentitiesには、 テレビチャンネルに関する情報が含まれていることに注意してください。

ペイロードの説明

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

ビデオコンテンツのエンティティタイプ。ビデオコンテンツのエンティティタイプについては、[ビデオコンテンツのエンティティタイプ](../video-skills-fire-tv-apps/entity-types-for-video-content.html)を参照してください。このリストに加え、Alexa Skills Kitには、マルチモーダルデバイス用の新しいタイプ (LISTTYPESORTTYPE)が追加されています。

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

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

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

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

例: MEDIATYPEVIDEOACTORGENREFRANCHISESEASONEPISODE

文字列
value
(必須)

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

例: インターステラーPBS

文字列
externalIds

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

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

オブジェクト
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形式の文字列
contentType

ContentTypeは、検索結果で返されたビデオのコンテンツタイプを示します。録画された映画やテレビ番組を送信する場合、contentTypeRECORDINGに設定されます。ライブのテレビ番組に関する情報が結果に含まれる場合、contentTypeLIVEに設定されます。オンデマンドのコンテンツが結果に含まれる場合、contentTypeON_DEMANDに設定されます。

ContentTypeは、ユーザーにプロンプトを提供する際にも使用されます。たとえば、contentTypeLIVEの場合、「CBSで現在放送中のアカデミー賞はこちらです」などのプロンプトがAlexaから提供されます。 contentTypeRECORDINGの場合は、「アカデミー賞はこちらです」などのプロンプトが提供されます。

例: RECORDINGLIVEON_DEMAND

列挙型
locale
(必須)

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

例:en-USen-GBde-DE

文字列
Gracenote

外部Gracenote ID。

例: ST0000000666661

文字列
entityMetadata

チャンネルに関連付けられたメタデータのマップ。

オブジェクト
channelCallSign

チャンネルのコールサイン。

例: KBTC

文字列
channelNumber

チャンネル番号。

例: 1234

整数

Lambdaのレスポンス

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

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

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

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

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

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

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

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

レスポンスの例(チャンネルナビゲーション)

チャンネル変更のシナリオに関連するGetPlayableItemsResponseの例を次に示します。

{
    "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": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}

ペイロードの説明

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

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

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

文字列
mediaItems
(必須)

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

リスト
mediaIdentifier
(必須)

mediaItemの識別子。

オブジェクト
id
(必須)

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

文字列