GetDisplayableItemsMetadataディレクティブ


GetDisplayableItemsMetadataディレクティブ

GetDisplayableItemsに対するLambdaのレスポンスをAlexaが受信すると、VideoContentProvider APIがLambdaにGetDisplayableItemsMetadataディレクティブをすぐに返します。GetDisplayableItemsMetadataディレクティブの目的は、コンテンツを再生することではなく、検索結果を適切に表示するための情報を取得することです。

次の図は、Alexaディレクティブとそれに対するLambdaのレスポンスを示しています。

GetDisplayableItemsMetadataディレクティブとLambdaのGetDisplayableItemsMetadataResponse

GetDisplayableItemsMetadataディレクティブの発話

GetDisplayableItemsMetadataディレクティブの送信をAlexaに促すような発話はありません。このディレクティブは、GetDisplayableItemsに対するLambdaのレスポンスを受信したAlexaがフォローアップとして送信します。

GetDisplayableItemsMetadataディレクティブの処理

Alexaは、検索結果をデバイスに表示する直前にGetDisplayableItemsMetadataを送信します。したがって、Alexaからこのディレクティブが送信されるシナリオは、検索、閲覧、ランディングページのいずれかとなります。

このディレクティブに含まれるのは、Alexaがメタデータを必要としているid値のリストだけです。id値は、Lambdaから送信された直前のGetDisplayableItemsResponseで返されます。

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"
                },
                {
                    "id": "channelId://provider1.channel.rp.1234-2345-63435-asdf"
                }
            ]
        }
    }
}

ペイロードの説明

GetDisplayableItemsMetadataディレクティブのpayloadフィールドについて次の表で説明します。

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

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

例:en-USen-GBde-DE

文字列
mediaIdentifiers
(必須)

メディアの`id`値のリストが格納されます。

配列
id
(必須)

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

文字列

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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true",
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

レスポンスのペイロードの例

GetDisplayableItemsMetadataResponsepayloadオブジェクトには、メディアに応じてさまざまなフィールドが格納されます。次のレスポンス例は、各種メディアのpayloadを示しています。

オンデマンドの映画におけるレスポンスのペイロードの例

{
    "payload": {
        "searchResults": [
            {
                "name": "インターステラー",
                "contentType": "ON_DEMAND",
                "releaseYear": "2014",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "インターステラーの画像",
                    "sources": [
                        {
                            "url": "http://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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://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": "http://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": "http://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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "viewingDisplayString": "エピソードを表示"
            }
        ]
    }
}

ペイロードの説明

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

ペイロードの説明
フィールド 説明 データ型
searchResults
(必須)
検索結果のリスト。 リスト
name
(必須)

ビデオの名前。再生されるビデオについてのプロンプトをユーザーに提供する目的で使用します。たとえば、「インターステラーはこちらです」などです。

例: インターステラー

文字列
contentType

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

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

例: RECORDINGLIVEON_DEMAND

列挙型
releaseYear

ビデオのリリース年。画面にアイテムを表示する際にリリース年を表示する目的で使用されます。

2018
文字列
selectionAction
(必須)

ユーザーがこのアイテムを選択したときのエンティティの閲覧方法についての指示です。たとえば、検索結果を送信する際、類似するアイテムをグループ化することがあります。映画やテレビ番組は、ジャンル、俳優などでグループ化できます。このような場合、グループを選択してアイテムをドリルダウンすることで、結果をさらに表示することができます。

次の列挙値を使用できます。

  • BROWSE: グループ化されたエンティティでブラウズノードアイテムを取得し、結果をさらに表示できることを意味します。この場合、Alexaは最終的に、選択されたエンティティidのGetBrowseNodeItemsを呼び出します。
  • PLAY: 指定のエンティティはグループ化されていないため、選択すれば再生できることを意味します。この場合、Alexaは最終的に、選択されたエンティティidGetPlayableItemsMetadataを呼び出します。

例: BROWSEPLAY

列挙型
thumbnailImage
(必須)

画像の情報。画面に結果アイテムの画像を表示する目的で使用されます。

例:

 {
  "contentDescription": "string",
  "sources": [
    {
      "url": "string",
      "size": "string",
      "widthPixels": integer,
      "heightPixels": integer
    },
    {
      "url": "string",
      "size": "string",
      "widthPixels": integer,
      "heightPixels": integer
    },
    { ... }
  ]
} 

オブジェクト
contentDescription
文字列
sources
配列
runtime
ビデオの再生時間についての詳細。 オブジェクト
runTimeInMilliseconds
ビデオの再生時間(ミリ秒)。

例: 271871324

長整数
displayString(runtime)
ビデオの再生時間を表すフォーマットされた表示文字列。画面に再生時間を表示する目的で使用されます。

例: 2時間30分

文字列
closedCaption
ビデオや表示情報で字幕が利用できるかどうかについての詳細。 オブジェクト
status(closedCaption)

ビデオで字幕が利用できるかどうか。次の値を含む列挙値です。

  • AVAILABLE: ビデオで字幕が利用できることを意味します。
  • NOT_AVAILABLE: ビデオで字幕が利用できないことを意味します。

例: AVAILABLENOT_AVAILABLE

列挙型
displayString(closedCaption)

画面に表示される、字幕を表すフォーマットされた表示文字列。

例: 字幕

文字列
series

シリーズに関するメタデータ(このアイテムがシリーズの一部である場合)。この情報は、テレビ番組にのみ設定してください。ここに値が設定されている場合は、その情報を使用してユーザーに対するプロンプトが提供されます(例:「『ビッグバン・セオリー』のシーズン1、エピソード4はこちらです」)。

オブジェクト
seasonNumber

ビデオのシーズン番号。

例: 1

文字列
episodeNumber

ビデオのエピソード番号。

例: 3

文字列
seriesName
episodeName

エピソード名。

例: 4

文字列
absoluteViewingPositionMilliseconds
(必須)

ユーザーの視聴履歴に基づいたビデオの進行状況オフセット(ミリ秒)。ユーザーに視聴履歴がある場合、このフィールドが表すオフセットは0より大きくなります。結果アイテムで進行状況バーを表示して、ユーザーが以前どこまで視聴したかを示す目的で使用されます。

例: 1248625

長整数
parentalControl
(必須)

ユーザーとビデオに基づくペアレンタルコントロール情報。

オブジェクト
pinControl
(必須)

このフィールドは、このビデオのユーザーに対して、設定に基づくペアレンタルコントロールが必要であるかどうかを示します。次の2つの値を含む列挙値です。

  • REQUIRED: ユーザーの設定に基づくペアレンタルコントロールがこのアイテムに適用されることを意味します。これが設定されている場合は、アイテムにロックアイコンが表示されます。これにより、そのアイテムにはペアレンタルコントロールが適用されており、ユーザーがビデオを視聴するにはPINの入力が必要であることがわかります。
  • NOT_REQUIRED: ユーザーの設定に基づくペアレンタルコントロールがこのアイテムには適用されないことを意味します。

例: REQUIREDNOT_REQUIRED

列挙型
viewingDisplayString

表示文字列は結果アイテムと共に画面に表示され、すぐに再生できるのか、または購入・レンタル・定期購入する必要があるのかをユーザーに示します。非消費型アイテムのステータスに基づいて、異なる文字列を使用できます。この文字列は、リクエストで送信されたロケールに基づいてローカライズする必要があります。

例: 今すぐ再生定期購入

文字列
reviews
ビデオのレビューに関する情報。 リスト
totalReviewCount
ビデオの合計レビュー数。

例: 13425

長整数
type(review)
情報の基となるレビューのタイプ。

例: FIVE_STAR

列挙型
ratingDisplayString
上記のタイプとレビューに基づくビデオの評価。検索結果に含まれる各アイテムの下にその評価を表示する目的で使用されます。

例: 4.06

文字列
rating
ビデオのレーティングに関連した情報。 オブジェクト
category(rating)
ビデオのレーティングカテゴリ。たとえば、PG-13などです。このビデオが視聴される地域で適用されるレーティングとなります。また、レーティングの値はコンテンツによっても異なる場合があります。たとえば、映画の場合はMPAAレーティング(「PG-13」など)を、テレビ番組の場合はテレビレーティング(「TV-PG」など)を返します。

例: PG-13TV-PG

文字列
networkDetails

プログラムを放映しているネットワークについての情報。たとえば、CBSが放送する「ビッグバン・セオリー」の新しいエピソードや、ESPNがライブで放送するサッカーの試合などが該当します。オンデマンドコンテンツの場合は、HBOが制作した「ゲーム・オブ・スローンズ」を配信するAmazonプライム・ビデオなどです。結果アイテムがチャンネルのライブ番組(contentType = LIVE)である場合、そのメタデータがこのオブジェクトに格納されます。

リスト
channel

ビデオを放送しているチャンネルに関する情報。

オブジェクト
number(channel)
チャンネル番号。

例: 1234

callSign(channel)
PBSなどのコールサインでチャンネルを指定します。

例: PBS

文字列
affiliateCallSign
KCTS9などの地方系列局コールサインでチャンネルを指定します。

例: KCTS9

uri(channel)
チャンネルのURI(例:「entity://provider/channel/12307」)。
channelMetadata

指定されたチャンネルに関する追加情報を指定します。

オブジェクト
name(channelMetadata)
チャンネルを識別する別の値(「FOX」など)。 文字列
image(channelMetadata)

例:http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg

airingDetails

このオブジェクトには、コンテンツがいつ放送されるかに関する情報が含まれます。

リスト
isLiveBroadcast

このコンテンツがリアルタイムで放送されているかどうか。NFLフットボールの試合中継や、アカデミー賞、エミー賞のようなショーなど、リアルタイムで放送されるライブイベントの場合、trueに設定します。

実際に放送される時刻よりも前に撮影されたコンテンツの場合は、falseに設定します。たとえば、毎週木曜日に放送される「ビッグバン・セオリー」の新しいエピソードなどが該当します。また、リアルタイムでは二度と行われない過去のフットボールの試合など、一度リアルタイムでストリーム配信されたコンテンツの場合も、falseに設定する必要があります。

例:truefalse

ブール型
end

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

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

ISO 8601形式の文字列
start

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

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

ISO 8601形式の文字列