GetPlayableItemsMetadataディレクティブ
GetPlayableItemsに対するLambdaのレスポンスをAlexaが受信すると、すぐにVideoContentProvider APIがGetPlayableItemsMetadataディレクティブを送信します。このディレクティブは、GetPlayableItemsで返されたアイテムのメタデータを取得するためのフォローアップとして送信されます。
下の図は、Alexaディレクティブとそれに対するLambdaのレスポンスを示しています。
- GetPlayableItemsMetadataディレクティブの発話
- GetPlayableItemsMetadataディレクティブの処理
- GetPlayableItemsMetadataの例
- Lambdaのレスポンス
- ペイロードの説明
GetPlayableItemsMetadataディレクティブの発話
GetPlayableItemsMetadataディレクティブの送信をAlexaに促すような発話はありません。このディレクティブは、GetPlayableItemsに対するLambdaのレスポンスを受信したAlexaがフォローアップとして送信します。
GetPlayableItemsMetadataディレクティブの処理
GetPlayableItemsMetadataの目的は、リクエストされたアイテムの再生を開始するうえで必要なメタデータを取得することです。Alexaが正しい音声レスポンスを提供してコンテンツの再生を開始できるよう、Lambdaのレスポンスには基本的なメタデータを含める必要があります。
GetDisplayableItemsMetadataと同様に、GetPlayableItemsMetadataディレクティブに含まれるのは、Alexaが（メディアを再生するために）メタデータを必要としているコンテンツのid値だけです。検索結果の表示に必要となるメタデータは一切レスポンスに含めないでください。
GetPlayableItemsMetadataの例
GetPlayableItemsMetadataディレクティブの例を次に示します。この例では、recordingId://provider1.dvr.rp.1234-2345-63434-asdfを値に持つmediaIdentifierのメタデータをAlexaがリクエストしています。返すのはGetPlayableItemsMetadataディレクティブで指定されたエンティティid値のメタデータのみです。
{
"directive": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
"name": "GetPlayableItemsMetadata",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "videoDevice-001",
"cookie": {
}
},
"payload": {
"locale": "ja-JP",
"mediaIdentifier": {
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
}
}
}
}
チャンネル変更に使用されるGetPlayableItemsMetadataディレクティブもほぼ同じですが、mediaIdentifierのidが異なる場合があります。その例を次に示します。
"payload": {
"locale": "ja-JP",
"mediaIdentifier": {
"id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
}
}
このケースでは、idが特定のメディアタイトルではなくチャンネルに関連付けられています。
Lambdaのレスポンス
Lambdaのレスポンス（GetPlayableItemsMetadataResponse）には、再生に必要となるメタデータ情報と、ビデオの再生前に成功のプロンプトを提供するために必要となるメタデータ情報のみを含める必要があります。GetPlayableItemsMetadataResponseとGetDisplayableItemsMetadataResponseはよく似ていますが、GetPlayableItemsMetadataResponseにはplaybackContextTokenが存在します。このトークンには、Alexaがウェブプレーヤーに渡す識別子が含まれています。playbackContextTokenは、対象のメディアに関して開発者が決定する識別子です。
AlexaがplaybackContextTokenをウェブプレーヤーに送信すると、その識別子がウェブプレーヤーで再生URLに変換されます。このプロセスについては、手順4： ウェブプレーヤーでメディア再生URLを取得する方法を理解するで説明しています。前出のコード例で、playbackContextTokenが文字列化されたオブジェクト（streamUrlパラメーターとtitleパラメーターから成るキーと値のペア）になっているのは、この形式がサンプルウェブプレーヤーで想定されているためです。
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"＜ビデオタイトル＞\"}",
この識別子を処理するウェブプレーヤーのコーディングによっては、単純に文字列などの形式を使用することもあります。
ON_DEMAND（VOD）メディアのレスポンスは、LIVE（リニア）メディアのレスポンスとは異なります。contentTypeが異なるだけでなく、LIVEのレスポンスにはnetworkDetailsが含まれます。
レスポンスの例：オンデマンドのテレビ番組
ビデオオンデマンド（VOD）コンテンツのレスポンスの例を次に示します。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetPlayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "ビッグバン・セオリー",
"contentType": "ON_DEMAND",
"series": {
"seasonNumber": "1",
"episodeNumber": "2",
"seriesName": "ビッグバン・セオリー",
"episodeName": "ターミネーターキャメロンVSオタクの法則"
},
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"＜ビデオタイトル＞\"}",
"parentalControl": {
"pinControl": "REQUIRED"
},
"absoluteViewingPositionMilliseconds": 1232340
}
]
}
}
}
レスポンスの例：ライブの映画
ライブコンテンツのレスポンスの例を次に示します。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetPlayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "インターステラー",
"contentType": "LIVE",
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"＜ビデオタイトル＞\"}",
"parentalControl": {
"pinControl": "REQUIRED"
},
"networkDetails": [
{
"channel": {
"callSign": "PBS",
"affiliateCallSign": "KCTS9"
},
"channelMetadata": {
"name": "代替チャンネル名"
},
"airingDetails": [
{
"isLiveBroadcast": "true",
"start": "2018-01-24T00:00:00Z",
"end": "2018-01-24T02:30:00Z"
}
]
}
]
}
]
}
}
}
レスポンスの例：チャンネル変更のシナリオ
チャンネル変更のシナリオでのレスポンスの例を次に示します。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetPlayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "インターステラー",
"contentType": "LIVE",
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"＜ビデオタイトル＞\"}",
"parentalControl": {
"pinControl": "REQUIRED"
},
"networkDetails": [
{
"channel": {
"callSign": "PBS",
"affiliateCallSign": "KCTS9"
},
"channelMetadata": {
"name": "代替チャンネル名"
},
"airingDetails": [
{
"isLiveBroadcast": "true",
"start": "2018-01-24T00:00:00Z",
"end": "2018-01-24T02:30:00Z"
}
]
}
]
}
]
}
}
}
ペイロードの説明
次の表は、GetPlayableItemsMetadataResponseレスポンスのペイロードについて説明しています。
| フィールド | 説明 | データ型 |
|---|---|---|
searchResults（必須） |
検索結果のリスト。 | リスト |
name（必須） |
ビデオの名前。再生されるビデオについてのプロンプトをユーザーに提供する目的で使用します。たとえば、「インターステラーはこちらです」などです。 例： |
文字列 |
contentType（必須） |
例： |
列挙型 |
playbackContextToken（必須） |
その後の識別のためにエンティティをシステムに逆マッピングするためのトークン。開発者側で逆マッピングによってエンティティを識別できれば、どのような文字列識別子を送信しても構いません。このトークンはAlexaからは認識できず、再生目的でデバイスに送信されます。メタデータ情報を取得したときと同じメディア識別子が再生に必要であれば、それを使用して構いません。または、再生に必要な追加情報を含んだ別の文字列をシリアル化して使用することもできます。 注： サンプルウェブプレーヤーを使用する場合、 |
不透明型の文字列 |
parentalControl（必須） |
ユーザーとビデオに基づくペアレンタルコントロール情報。 |
オブジェクト |
pinControl（必須） |
このフィールドは、このビデオのユーザーに対して、設定に基づくペアレンタルコントロールが必要であるかどうかを示します。次の2つの値を取る列挙値です。
例： |
列挙型 |
networkDetails（省略可能） |
番組を放送しているネットワークについての情報。たとえば、「ビッグバン・セオリー」の新しいエピソードであればCBS、サッカーの生中継であればESPNといった放送局の情報です。オンデマンドコンテンツの場合は、たとえばAmazonプライム・ビデオで配信される「ゲーム・オブ・スローンズ」であれば、制作局のHBOとなります。結果アイテムがチャンネルのライブ番組（ |
リスト |
channel（省略可能） |
ビデオを放送しているチャンネルに関する情報。 |
オブジェクト |
callSign（channel）（省略可能） |
PBSなどのコールサインでチャンネルを指定します。
例： |
文字列 |
affiliateCallSign（channel）（省略可能） |
KCTS9といった地方系列局のコールサインでチャンネルを指定します。
例： |
文字列 |
channelMetadata（省略可能） |
指定されたチャンネルの追加情報を指定します。 |
オブジェクト |
name（channelMetadata）（省略可能） |
「FOX」など、チャンネルを識別する別の値。 | 文字列 |
airingDetails（省略可能） |
このオブジェクトには、コンテンツがいつ放送されるかの情報が含まれます。 |
リスト |
isLiveBroadcast（省略可能） |
このコンテンツがリアルタイムで放送されているかどうか。NFLフットボールの試合中継や、アカデミー賞、エミー賞のような授賞式など、リアルタイムで放送されるライブイベントの場合は、 実際に放送される時刻よりも前に撮影されたコンテンツの場合は、 例： |
ブール型 |
start（省略可能） |
タイムウィンドウの開始時刻。 例： |
ISO 8601形式の文字列 |
end（省略可能） |
タイムウィンドウの終了時刻。 例： |
ISO 8601形式の文字列 |
networkDetails（省略可能） |
番組を放送しているネットワークについての情報。たとえば、「ビッグバン・セオリー」の新しいエピソードであればCBS、サッカーの生中継であればESPNといった放送局の情報です。オンデマンドコンテンツの場合は、たとえばAmazonプライム・ビデオで配信される「ゲーム・オブ・スローンズ」であれば、制作局のHBOとなります。結果アイテムがチャンネルのライブ番組（ |
リスト |
series（省略可能） |
シリーズに関するメタデータ（このアイテムがシリーズの一部である場合）。この情報は、テレビ番組にのみ設定してください。ここに値が設定されている場合は、その情報を使用してユーザーにプロンプトが提供されます（例：「『ビッグバン・セオリー』のシーズン1、エピソード4はこちらです」）。 |
オブジェクト |
seasonNumber（series）（省略可能） |
ビデオのシーズン番号。 例： |
文字列 |
episodeNumber（series）（省略可能） |
ビデオのエピソード番号。 例： |
文字列 |
episodeName（series）（省略可能） |
エピソード名。 例： |
文字列 |
seriesName（series）省略可能 |
シリーズの名前です。 | 文字列 |
absoluteViewingPositionMilliseconds（必須） |
ユーザーの視聴履歴に基づいたビデオの進行状況オフセット（ミリ秒）。ユーザーに視聴履歴がある場合、このフィールドが表すオフセットは0より大きくなります。結果アイテムで進行状況バーを表示して、ユーザーが以前どこまで視聴したかを示す目的で使用されます。 例： |
長整数 |