GetDisplayableItemsMetadataディレクティブ
GetDisplayableItemsに対するLambdaのレスポンスをAlexaが受信すると、すぐにVideoContentProvider APIがGetDisplayableItemsMetadataディレクティブをLambdaに返します。GetDisplayableItemsMetadataディレクティブの目的は、コンテンツを再生することではなく、検索結果を適切に表示するための情報を取得することです。
次の図は、このAlexaディレクティブとそれに対するLambdaのレスポンスを示しています。
- GetDisplayableItemsMetadataディレクティブの発話
- GetDisplayableItemsMetadataディレクティブの処理
- GetDisplayableItemsMetadataの例
- ペイロードの説明
- Lambdaのレスポンス
- レスポンスの例
- レスポンスのペイロードの例
- ペイロードの説明
mediaIdentifierオブジェクトからの画像サイズデータの取得
GetDisplayableItemsMetadataディレクティブの発話
GetDisplayableItemsMetadataディレクティブの送信をAlexaに促すような発話はありません。このディレクティブは、GetDisplayableItemsに対するLambdaのレスポンスを受信したAlexaがフォローアップとして送信します。
GetDisplayableItemsMetadataディレクティブの処理
Alexaは、検索結果をデバイスで表示する直前にGetDisplayableItemsMetadataを送信します。したがって、Alexaからこのディレクティブが送信されるシナリオは、検索、閲覧、ランディングページのいずれかとなります。
このディレクティブに含まれるのは、Alexaがメタデータを必要としているid値のリストだけです。id値は、その前に送信したGetDisplayableItemsResponseでLambdaから返したものです。
LambdaのGetDisplayableItemsResponseレスポンスには、アイコン、バッジ、selectionActionなどに関するメタデータのほか、ユーザーに対するAlexaの音声レスポンスのメタデータを含める必要があります。
ユーザーに表示するアートワークは、タイトルにふさわしいものにしてください。アートワークを使用すると、ユーザーが検索結果でおすすめのコンテンツを識別しやすくなります。
GetDisplayableItemsMetadataの例
GetDisplayableItemsMetadataディレクティブの例を次に示します。
{
"directive": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
"name": "GetDisplayableItemsMetadata",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "videoDevice-001",
"cookie": {
}
},
"payload": {
"locale": "ja-JP",
"mediaIdentifiers": [
{
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf",
"displayContext": {
"imageWidth": "480px",
"imageHeight": "270px",
"imageAspectRatio": "16:9",
"imageSize": "MEDIUM"
}
},
{
"id": "channelId://provider1.channel.rp.1234-2345-63435-asdf",
"displayContext": {
"imageWidth": "480px",
"imageHeight": "270px",
"imageAspectRatio": "16:9",
"imageSize": "MEDIUM"
}
}
]
}
}
}
ペイロードの説明
次の表は、GetDisplayableItemsMetadataディレクティブのpayloadのフィールドについて説明しています。
| フィールド | 説明 | データ型 |
|---|---|---|
locale（必須） |
ユーザーのロケール。検索結果に対応する表示可能な情報を取得するために必要となります。ロケールの形式は、Network Working Groupの「Best Current Practice 47（BCP-47）」（英語のみ）で規定されている言語の形式と同じです。認識されないロケールを受信した場合は、デフォルトで 例： |
文字列 |
mediaIdentifiers（必須） |
メディアの |
配列 |
id（必須） |
ビデオアイテムの識別子。後続の |
文字列 |
Lambdaのレスポンス
Lambdaのレスポンスにはメタデータ情報が含まれている必要があります。この情報は、（Amazonが提供する）デバイスでテンプレートに値を設定し、画面に検索結果を表示するうえで必要となります。レスポンスに含まれるのは、表示に関連した情報だけです。この場合、再生に関する情報は必要ありません。
レスポンスの例
Lambdaから送信されるGetDisplayableItemsMetadataResponseの例を次に示します。このレスポンスには、デバイスに表示するアイテムのid値のリストが含まれています。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetDisplayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "ビッグバン・セオリー",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "BROWSE",
"thumbnailImage": {
"contentDescription": "ビッグバン・セオリーの画像",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2時間49分"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "字幕"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "ビッグバン・セオリー",
"episodeName": "パイロット"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "購入オプション",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
},
{
"name": "ビッグバン・セオリー",
"contentType": "LIVE",
"releaseYear": "2011",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "ビッグバン・セオリーの画像",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "30分"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "字幕"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "ビッグバン・セオリー",
"episodeName": "パイロット"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "今すぐ再生",
"rating": {
"category": "TV-PG"
},
"networkDetails": [
{
"channel": {
"number": "1234",
"callSign": "PBS",
"affiliateCallSign": "KCTS9",
"uri": "someUrl"
},
"channelMetadata": {
"name": "代替チャンネル名",
"image": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
},
"airingDetails": [
{
"isLiveBroadcast": "true",
"end": "2018-01-24T02:30:00Z",
"start": "2018-01-24T00:00:00Z"
}
]
}
]
}
]
}
}
}
レスポンスのペイロードの例
GetDisplayableItemsMetadataResponseのpayloadオブジェクトには、メディアに応じてさまざまなフィールドが格納されます。次のレスポンス例は、各種メディアのpayloadを示しています。
レスポンスのペイロードの例：オンデマンドの映画
{
"payload": {
"searchResults": [
{
"name": "インターステラー",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "インターステラーの画像",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2時間49分"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "字幕"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "購入オプション",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
}
]
}
}
ペイロードの例：オンデマンドのテレビ番組
{
"payload": {
"searchResults": [
{
"name": "ビッグバン・セオリー",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "ビッグバン・セオリーの画像",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2時間49分"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "字幕"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "ビッグバン・セオリー",
"episodeName": "パイロット"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "購入オプション",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
}
]
}
}
ペイロードの例：ライブコンテンツ
{
"payload": {
"searchResults": [
{
"name": "インターステラー",
"contentType": "LIVE",
"releaseYear": "2011",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "インターステラーの画像",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2時間30分"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "字幕"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "今すぐ再生",
"rating": {
"category": "PG-13"
},
"networkDetails": [
{
"channel": {
"number": "1234",
"callSign": "PBS",
"affiliateCallSign": "KCTS9",
"uri": "someUrl"
},
"channelMetadata": {
"name": "代替チャンネル名",
"image": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
},
"airingDetails": [
{
"isLiveBroadcast": "true"
"end": "2018-01-24T02:30:00Z",
"start": "2018-01-24T00:00:00Z"
}
]
}
]
}
]
}
}
ペイロードの例：閲覧可能なコンテンツ
{
"payload": {
"searchResults": [
{
"name": "ビッグバン・セオリー",
"contentType": "RECORDING",
"selectionAction": "BROWSE",
"thumbnailImage": {
"contentDescription": "ビッグバン・セオリーの画像",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"viewingDisplayString": "エピソードを表示"
}
]
}
}
ペイロードの説明
次の表は、GetDisplayableItemsMetadataResponseのpayloadのフィールドについて説明しています。
| フィールド | 説明 | データ型 |
|---|---|---|
searchResults（必須） |
検索結果のリスト。 | リスト |
name（必須） |
ビデオの名前。再生されるビデオについてのプロンプトをユーザーに提供する目的で使用します。たとえば、「インターステラーはこちらです」などです。 例： |
文字列 |
contentType（必須） |
例： |
列挙型 |
itemType（必須） |
Alexaは両方のディレクティブに対するレスポンス（ 例： |
列挙型 |
releaseYear（省略可能） |
ビデオのリリース年。画面にアイテムを表示する際にリリース年を表示する目的で使用されます。 2018 |
文字列 |
selectionAction（必須） |
ユーザーがこのアイテムを選択したときのエンティティの閲覧方法についての指示です。たとえば、検索結果を送信する際、類似するアイテムをグループ化することがあります。映画やテレビ番組は、ジャンル、俳優などでグループ化できます。このような場合、グループを選択してアイテムをドリルダウンすることで、結果をさらに表示することができます。 次の列挙値を使用できます。
例： |
列挙型 |
thumbnailImage（必須） |
画像の情報。画面に結果アイテムの画像を表示する目的で使用されます。URLのプレフィックスは 例： {
"contentDescription": "string",
"sources": [
{
"url": "string",
"size": "string",
"widthPixels": integer,
"heightPixels": integer
},
{
"url": "string",
"size": "string",
"widthPixels": integer,
"heightPixels": integer
},
{ ... }
]
}
|
オブジェクト |
runtime（省略可能） |
ビデオの再生時間についての詳細。 | オブジェクト |
runTimeInMilliseconds（省略可能） |
ビデオの再生時間（ミリ秒）。
例： |
長整数 |
displayString（runtime）（省略可能） |
ビデオの再生時間を表すフォーマットされた表示文字列。画面に再生時間を表示する目的で使用されます。
例： |
文字列 |
closedCaption（省略可能） |
ビデオや表示情報でクローズドキャプションが利用できるかどうかについての詳細。 | オブジェクト |
status（closedCaption）（省略可能） |
ビデオでクローズドキャプションが利用できるかどうか。次の値を取る列挙値です。
例： |
列挙型 |
displayString（closedCaption）（省略可能） |
画面に表示される、クローズドキャプションを表すフォーマットされた表示文字列。 例： |
文字列 |
series（省略可能） |
シリーズに関するメタデータ（このアイテムがシリーズの一部である場合）。この情報は、テレビ番組にのみ設定してください。ここに値が設定されている場合は、その情報を使用してユーザーにプロンプトが提供されます（例：「『ビッグバン・セオリー』のシーズン1、エピソード4はこちらです」）。 |
オブジェクト |
seasonNumber（series）（省略可能） |
ビデオのシーズン番号。 例： |
文字列 |
episodeNumber（series）（省略可能） |
ビデオのエピソード番号。 例： |
文字列 |
episodeName（series）（省略可能） |
エピソード名。 例： |
文字列 |
absoluteViewingPositionMilliseconds（必須） |
ユーザーの視聴履歴に基づいたビデオの進行状況オフセット（ミリ秒）。ユーザーに視聴履歴がある場合、このフィールドが表すオフセットは0より大きくなります。結果アイテムで進行状況バーを表示して、ユーザーが以前どこまで視聴したかを示す目的で使用されます。 例： |
長整数 |
parentalControl（必須） |
ユーザーとビデオに基づくペアレンタルコントロール情報。 |
オブジェクト |
pinControl（必須） |
このフィールドは、このビデオのユーザーに対して、設定に基づくペアレンタルコントロールが必要であるかどうかを示します。次の2つの値を取る列挙値です。
例： |
列挙型 |
viewingDisplayString（省略可能） |
表示文字列は結果アイテムと共に画面に表示され、すぐに再生できるのか、または購入・レンタル・定期購入などが必要なのかをユーザーに示します。非消費型アイテムのステータスに基づいて、異なる文字列を使用できます。この文字列は、リクエストで送信されたロケールに基づいてローカライズする必要があります。 例： |
文字列 |
reviews（省略可能） |
ビデオのレビューに関する情報。 | リスト |
totalReviewCount（省略可能） |
ビデオの合計レビュー数。
例： |
長整数 |
type（review）（省略可能） |
情報の基となるレビューのタイプ。
例： |
列挙型 |
ratingDisplayString（省略可能） |
上記のタイプとレビューに基づくビデオの評価。検索結果に含まれる各アイテムの下にその評価を表示する目的で使用されます。
例： |
文字列 |
rating（省略可能） |
ビデオのレーティングに関連した情報。 | オブジェクト |
ratingCategory（省略可能） |
ビデオのレーティングカテゴリー（PG-13など）。このレーティングはこのビデオが視聴される地域で適用されます。また、レーティングの値はコンテンツによっても異なる場合があります。たとえば、映画の場合はMPAAレーティング（「PG-13」など）を、テレビ番組の場合はテレビレーティング（「TV-PG」など）を送信できます。
例： |
文字列 |
recording（省略可能） |
録画に関連する情報。現在のところ、構造体のフィールドは |
オブジェクト |
status（recording）（省略可能） |
コンテンツの録画ステータス。次の列挙値を使用できます。
例： |
文字列 |
contentFreshness（省略可能） |
コンテンツの鮮度についての詳細。 |
オブジェクト |
state（contentFreshness）（省略可能） |
Alexaに結果を返しているプロバイダーの新しいコンテンツであるかどうか。使用できる列挙値は 例： |
文字列 |
networkDetails（省略可能） |
番組を放送しているネットワークについての情報。たとえば、「ビッグバン・セオリー」の新しいエピソードであればCBS、サッカーの生中継であればESPNといった放送局の情報です。オンデマンドコンテンツの場合は、たとえばAmazonプライム・ビデオで配信される「ゲーム・オブ・スローンズ」であれば、制作局のHBOとなります。結果アイテムがチャンネルのライブ番組（ |
リスト |
channel（省略可能） |
ビデオを放送しているチャンネルに関する情報。 |
オブジェクト |
callSign（channel）（省略可能） |
PBSなどのコールサインでチャンネルを指定します。
例： |
文字列 |
affiliateCallSign（channel）（省略可能） |
KCTS9といった地方系列局のコールサインでチャンネルを指定します。
例： |
文字列 |
uri（channel）（省略可能） |
チャンネルのURIです（「entity://provider/channel/12307」など）。 | |
channelMetadata（省略可能） |
指定されたチャンネルの追加情報を指定します。 |
オブジェクト |
name（channelMetadata）（省略可能） |
「FOX」など、チャンネルを識別する別の値。 | 文字列 |
image（channelMetadata）（省略可能） |
例： |
文字列 |
airingDetails（省略可能） |
このオブジェクトには、コンテンツがいつ放送されるかの情報が含まれます。 |
リスト |
isLiveBroadcast（省略可能） |
このコンテンツがリアルタイムで放送されているかどうか。NFLフットボールの試合中継や、アカデミー賞、エミー賞のような授賞式など、リアルタイムで放送されるライブイベントの場合は、 実際に放送される時刻よりも前に撮影されたコンテンツの場合は、 例： |
ブール型 |
end（省略可能） |
タイムウィンドウの終了時刻。 例： |
ISO 8601形式の文字列 |
start（省略可能） |
タイムウィンドウの開始時刻。 例： |
ISO 8601形式の文字列 |
mediaIdentifier（必須） |
|
オブジェクト |
mediaIdentifierオブジェクトからの画像サイズデータの取得
GetDisplayableItemsMetadata APIは、カタログ内のアイテムに関連する情報を返します。返されるメタデータフィールドの1つがサムネイル画像のURLです。このURLは、検索結果、ランディングページ、カテゴリー選択の画面で表示される画像を読み込む際に使用されます。また、Echo Showデバイスにはさまざまなサイズと解像度があるため、このURLによって設定される画像コンテナのサイズと解像度もさまざまです。GetDisplayableItemsMetadataが返す画像がリクエスト元のデバイスに適合しない場合、ディスプレイによっては画像がゆがむことがあります。
これを回避するには、mediaIdentifierに属するdisplayContextオブジェクトのデータを使用します。
displayContextオブジェクトのデータの使用方法
displayContextオブジェクトには、次のフィールドがあります。
| フィールド | 型 | 必須／任意 |
|---|---|---|
imageAspectRatio |
比率（文字列型） 現時点では、 「2:1」、「16:10」、「16:9」のいずれか |
必須 |
imageHeight |
サイズ（文字列型） 例： 「480px」 |
任意 |
imageSize |
列挙型 imageSizeのプロパティを参照 |
必須 |
imageWidth |
サイズ（文字列型） 例： 「270px」 |
任意 |
リクエストのimageWidthフィールドとimageHeightフィールドにより、使用する画像のサイズを正確に把握できます。また、画像の最適な縦横比を指定するimageAspectRatioフィールドと、画像サイズを指定するimageSizeフィールドを使用して、画像を調整することも可能です。リクエストされた正確な比率やサイズの画像がない場合、スキルはまずimageAspectRatioを適用し、次にimageSizeを適用することで、画像を自動的に拡大・縮小します。
複数の画像を使用する場合、APIはまずimageAspectRatioでマッチングを行い、画像の伸長やトリミングを回避します。
各デバイスについて、APIが返す画像プロパティを以下に示します。開発者は、自身で決定した粒度の画像を提供することができます。たとえば、16:9の画像は、Echo Show 5を除くすべてのデバイスで拡大表示されます。ただし、各デバイスに適した解像度の画像を提供することも可能です。
imageSizeのプロパティ
以下は、imageSizeフィールドの列挙型プロパティの一覧です。
| プロパティ | 説明 | 推奨サイズ（ピクセル） 幅x高さ |
|---|---|---|
X_SMALL |
極小コンテナ内に表示 | 480x320 |
SMALL |
小さなコンテナ内に表示 | 720x480 |
MEDIUM |
中程度の大きさのコンテナ内に表示 | 960x640 |
LARGE |
大きなコンテナ内に表示 | 1200x800 |
X_LARGE |
特大コンテナ内に表示 | 1920x1280 |
Echo Showデバイスでサポートされる画像サイズ
サポートされる画像サイズは次のとおりです。
| デバイス | デバイスの解像度 | ヒーロータイトルの解像度 （ピクセル） |
ヒーロータイトルの 縦横比 |
検索結果の解像度 （ピクセル） |
検索結果の 縦横比 |
|---|---|---|---|---|---|
| Echo Show 10 第2世代 |
1280x800 | 1280x800 | 16:10 | 364x204 | 16:9 |
| Echo Show 5 | 960x480 | 960x480 | 2:1 | 368x184 | 2:1 |
| Echo Show 第1世代 |
1024x600 | 1024x600 | 16:10 | 564x320 | 16:9 |
| Echo Show 8 | 1280x800 | 1280x800 | 16:10 | 522x293 | 16:9 |
リクエストの例
{
"locale": "ja-JP",
"mediaIdentifiers": [
{
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-abcde",
"displayContext": {
"imageWidth": "480px",
"imageHeight": "270px",
"imageAspectRatio": "16:9",
"imageSize": "MEDIUM"
}
}
]
}