GetDisplayableItemsMetadata指令 (VSK Echo Show)
一旦Alexa收到您的Lambda对GetDisplayableItems的响应，VideoContentProvider API会立即将GetDisplayableItemsMetadata指令发送回您的Lambda。GetDisplayableItemsMetadata指令的目的是检索信息以正确显示搜索结果（而不是播放任何内容）。
下图显示了预期的Alexa指令和Lambda响应。
- GetDisplayableItemsMetadata指令的表述
- 处理GetDisplayableItemsMetadata指令
- GetDisplayableItemsMetadata示例
- 有效负载描述
- Lambda响应
- 响应示例
- 响应有效负载示例
- 有效负载描述
- 从
mediaIdentifier对象检索图像大小数据
GetDisplayableItemsMetadata指令的表述
无表述提示Alexa发送GetDisplayableItemsMetadata指令。相反，Alexa在收到您的Lambda对GetDisplayableItems的响应后，会发送此指令作为后续操作。
处理GetDisplayableItemsMetadata指令
在Alexa即将在设备上显示搜索结果之前，Alexa会发送GetDisplayableItemsMetadata。因此，Alexa可能会在搜索、浏览或登录页面场景中发送此指令。
该指令仅包含Alexa需要元数据的id值列表。id值是在您的Lambda发送的上个GetDisplayableItemsResponse期间由您返回的。
您的Lambda的GetDisplayableItemsResponse响应中应包含Alexa对用户的语音响应的元数据，以及有关图标、徽标、selectionAction等的元数据。
返回给用户的图像应适用于标题。图像应该让用户易于识别您在其搜索中推荐的内容。
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": "en-US",
"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必需 |
用户的区域设置，应当用于获取搜索结果的可显示信息。格式与网络工作组当前最佳实践47(BCP-47) 中为语言指定的格式相同的区域设置。如果您收到无法识别的区域设置，则默认设置为 示例： |
字符串 |
mediaIdentifiers必需 |
包含媒体的 |
数组 |
id必需 |
视频项目的标识符，用于在后续调用 |
字符串 |
Lambda响应
您的Lambda响应必须包含在设备上填充模板（由亚马逊提供）并在屏幕上呈现搜索结果所需的元数据信息。响应仅包含与显示相关的信息，在这种情况下不需要播放信息。
响应示例
以下是您的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": "The Big Bang Theory",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "BROWSE",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory图像",
"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": "2h 49m"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "The Big Bang Theory",
"episodeName": "Pilot"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "购买选项",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
},
{
"name": "The Big Bang Theory",
"contentType": "LIVE",
"releaseYear": "2011",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory图像",
"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 min"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "The Big Bang Theory",
"episodeName": "Pilot"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "Play Now",
"rating": {
"category": "TV-PG"
},
"networkDetails": [
{
"channel": {
"number": "1234",
"callSign": "PBS",
"affiliateCallSign": "KCTS9",
"uri": "someUrl"
},
"channelMetadata": {
"name": "Alternate Channel 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。
ON_DEMAND电影的响应有效负载示例
{
"payload": {
"searchResults": [
{
"name": "Interstellar",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "Interstellar Image",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2h 49m"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "购买选项",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
}
]
}
}
ON_DEMAND电视节目的有效负载示例
{
"payload": {
"searchResults": [
{
"name": "The Big Bang Theory",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory图像",
"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": "2h 49m"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "The Big Bang Theory",
"episodeName": "Pilot"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "购买选项",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
}
]
}
}
直播内容的有效负载示例
{
"payload": {
"searchResults": [
{
"name": "Interstellar",
"contentType": "LIVE",
"releaseYear": "2011",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "Interstellar Image",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2h 30 min"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "Play Now",
"rating": {
"category": "PG-13"
},
"networkDetails": [
{
"channel": {
"number": "1234",
"callSign": "PBS",
"affiliateCallSign": "KCTS9",
"uri": "someUrl"
},
"channelMetadata": {
"name": "Alternate Channel 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": "The Big Bang Theory",
"contentType": "RECORDING",
"selectionAction": "BROWSE",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory图像",
"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必需 |
视频的名称。此项用于向用户呈现有关将要播放的视频的提示。例如，“这是Interstellar”。 示例： |
字符串 |
contentType必需 |
示例： |
枚举 |
itemType必需 |
在收到您对这两项指令的响应 ( 示例： |
枚举 |
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可选 |
如果此项目是连续剧的一部分，则为有关该连续剧的元数据。应当仅对电视节目填写此信息。如果可用，这里的信息用于向用户呈现提示，例如，“这是'The Big Bang Theory'第1季第4剧集”。 |
对象 |
seasonNumber（连续剧）可选 |
视频的季编号。 示例： |
字符串 |
episodeNumber（连续剧）可选 |
视频的剧集编号。 示例： |
字符串 |
episodeName（连续剧）可选 |
剧集名称。 示例： |
字符串 |
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播出"The Big Bang Theory"的新剧集，或通过ESPN播出直播足球赛。对于点播内容，例如，这可以是显示HBO "Game of thrones"结果的Prime Video。如果结果项目表示频道上的直播节目( |
列表 |
channel（频道）可选 |
有关当前正在播放视频的频道的信息。 |
对象 |
callSign（频道）可选 |
通过呼叫信号（例如PBS）指定频道。
示例： |
字符串 |
affiliateCallSign（频道）可选 |
通过本地分台呼叫信号（如KCTS9）指定频道。
示例： |
字符串 |
uri (channel)可选 |
频道的URI，例如“entity://provider/channel/12307” | |
channelMetadata可选 |
提供有关指定频道的其他信息。 |
对象 |
name（频道元数据）可选 |
标识频道的另一个值，例如"FOX"。 | 字符串 |
image (channelMetadata)可选 |
示例： |
字符串 |
airingDetails可选 |
此对象包含有关何时播出内容的信息。 |
列表 |
isLiveBroadcast可选 |
内容是否为实时播放。对于实时发生的现场活动，如观看NFL橄榄球比赛，或奥斯卡或艾美奖等颁奖典礼，将此项设置为 对于在初始播放时间之前已拍摄好的内容，将此项设置为 示例： |
布尔值 |
end可选 |
时间窗口的结束时间。 示例： |
ISO 8601格式的字符串。 |
start可选 |
时间窗口的开始时间。 示例： |
ISO 8601格式的字符串。 |
mediaIdentifier必需 |
|
对象 |
从mediaIdentifier对象检索图像大小数据
GetDisplayableItemsMetadata API返回有关您目录中项目的相关信息。这些元数据字段之一是缩略图URL，它用于在屏幕上将图像作为搜索结果、登陆页面和类别选择的一部分加载。Echo Show设备的大小和分辨率各不相同，因此这些URL填充的图像容器的大小和分辨率也各不相同。如果GetDisplayableItemsMetadata返回的图像不适合请求它的设备，则图像在某些显示器上可能会失真。
为避免这种情况，请使用来自displayContext对象的数据，该对象属于mediaIdentifier。
如何使用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 |
显示在超小型容器中 | 480 x 320 |
SMALL |
显示在小型容器中 | 720 x 480 |
MEDIUM |
显示在中型容器中 | 960 x 640 |
LARGE |
显示在大型容器中 | 1200 x 800 |
X_LARGE |
显示在超大型容器中 | 1920 x 1280 |
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": "en-US",
"mediaIdentifiers": [
{
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-abcde",
"displayContext": {
"imageWidth": "480px",
"imageHeight": "270px",
"imageAspectRatio": "16:9",
"imageSize": "MEDIUM"
}
}
]
}
Last updated: 2021年5月24日
