GetPlayableItemsMetadata指令(VSK Echo Show)
一旦Alexa收到您的Lambda对GetPlayableItems的响应，VideoContentProvider API会立即发送GetPlayableItemsMetadata指令作为后续指令，以获取GetPlayableItems中返回的项目的元数据。
下图显示了Alexa指令和Lambda响应。
- GetPlayableItemsMetadata指令的表述
- 处理GetPlayableItemsMetadata指令
- GetPlayableItemsMetadata示例
- 广告对象
- Lambda响应
- 有效负载描述
GetPlayableItemsMetadata指令的表述
无表述提示Alexa发送GetPlayableItemsMetadata指令。相反，Alexa在收到您的Lambda对GetPlayableItems的响应后，会发送此指令作为后续操作。
处理GetPlayableItemsMetadata指令
GetPlayableItemsMetadata的目的是检索必要的元数据，以启动所请求项目的播放。您的Lambda响应应包括基本元数据，以便Alexa能够呈现正确的语音响应并启动内容播放。
与GetDisplayableItemsMetadata相似，GetPlayableItemsMetadata元数据指令仅包含特定内容id值，对于这些内容id值Alexa需要元数据（以播放媒体）。您的响应不应包含显示搜索结果所需的任何元数据。
GetPlayableItemsMetadata示例
以下为示例GetPlayableItemsMetadata指令。在该示例中，Alexa请求值为recordingId://provider1.dvr.rp.1234-2345-63434-asdf的mediaIdentifier的元数据。仅对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": "en-US",
"mediaIdentifier": {
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
}
}
}
}
频道更换GetPlayableItemsMetadata的指令与此一致，不同的是mediaIdentifier可能具有不同的id，如下所示：
"payload": {
"locale": "en-US",
"mediaIdentifier": {
"id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
}
}
在该情况下，id与频道相关而非特定媒体标题。
广告对象
advertising对象提供客户的广告ID和用于接收基于兴趣的广告的首选项。Alexa在声明自身提供广告的视频技能的请求中包含advertising对象。有关更多详情，请参阅Alexa广告ID。
要接收Alexa广告ID，您必须指明您的技能提供广告，发布隐私政策，并提交您的技能进行重新认证。
广告对象的结构
| 属性 | 描述 | 类型 | 是否必需？ |
|---|---|---|---|
advertisingId |
客户可重置的唯一标识符，该标识符映射至OpenRTB API specification的ifa属性。其格式设定为版本4 UUID字符串，由短横分隔(8-4-4-4-12)。示例： E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367。 |
字符串 | 是 |
limitAdTracking |
指明客户是否希望接收基于兴趣的广告。当客户选择退出基于兴趣的广告时，设置为true。limitAdTracking属性映射至OpenRTB API规范的lmt属性。 |
布尔值 | 是 |
示例设置
以下是指明客户选择不接收基于兴趣的广告的设置示例。
"advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": true
}
"advertising": {
"advertisingId": "00000000-0000-0000-0000-00000000",
"limitAdTracking": true
}
以下示例示出了指明客户选择接收基于兴趣的广告的设置。
"advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": false
}
广告所需的Video Skill API
要在播放期间允许流媒体内广告，以下Alexa Video Skill API将在GetPlayableItemsMetadata有效载荷中包含requestContext对象。
此对象将包含广告上下文，其中包含客户的广告首选项。对适用的API更新您技能的代码，以使用广告对象。有关这些API的详情，请参阅Alexa发送的指令。
设计您的技能，以使用来自每个请求的广告对象。在您的代码中，在对advertisingId的任何访问之前都要前置代码来验证limitAdTracking标记。如果limitAdTracking == true，则必须遵照客户的选择并禁用跟踪。
不要缓存广告属性，因为客户可以重置其ID并更改其首选项，以便在技能会话期间或之后的任何时间接收基于兴趣的广告。Alexa将下个请求中的最新值发送至您的技能。除非客户明确同意，否则不要将新的advertisingId与之前的advertisingId或与之前的advertisingId绑定的数据相关联。同样，除非客户明确同意，否则不要将任何个人数据与advertisingId关联。
如果客户选择不接收基于兴趣的广告，advertisingId可用于分析，但您必须禁用跟踪和基于兴趣的广告。在某些请求中，Alexa可能未包含广告对象。设计您的技能，以便在有和没有advertisingId的情况下运行。您必须尊重客户的退出选择。
示例GetPlayableItemsMetadata请求
以下是具有广告对象的GetPlayableItemsMetadata请求的示例。
{
"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": "en-US",
"mediaIdentifier": {
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
},
"requestContext": {
"advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": false
}
}
}
}
}
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\": \"Some Video Title\"}",
根据您对网页播放器进行编码以处理此标识符的方式，您可以直接使用字符串或其他格式。
对ON_DEMAND (VOD)媒体的响应不同于对LIVE（线性）媒体的响应。不仅contentType不同，LIVE响应还包含networkDetails.
ON_DEMAND电视节目的示例响应
以下响应示出了点播视频(VOD)内容的示例。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetPlayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "The Big Bang Theory",
"contentType": "ON_DEMAND",
"series": {
"seasonNumber": "1",
"episodeNumber": "2",
"seriesName": "The Big Bang Theory",
"episodeName": "The Terminator Decoupling"
},
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video 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": "Interstellar",
"contentType": "LIVE",
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video 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": "Interstellar",
"contentType": "LIVE",
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video 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必需 |
视频的名称。此项用于向用户呈现有关将要播放的视频的提示。例如，“这是Interstellar”。 示例： |
字符串 |
可选 |
|
|
contentType必需 |
示例： |
枚举 |
playbackContextToken必需 |
允许将实体映射回系统以进一步识别的令牌。您可以发送任何字符串标识符，只要您可以将其映射回去以标识您这边的实体即可。此令牌对Alexa来说是不透明的，并发送到设备用于播放。它可以是用于获取元数据信息的相同媒体标识符（如果该元数据信息是播放所需的），也可以是具有播放所需附加信息的不同序列化字符串。 注意： 如果您使用示例网页播放器，则 |
不透明字符串 |
parentalControl必需 |
家长监护信息基于用户和视频。 |
对象 |
pinControl必需 |
此字段指明，基于设置对于此视频用户是否需要家长监护。这是具有2个值的枚举。
示例： |
枚举 |
networkDetails可选 |
网络详细信息提供有关节目通过哪个网络播放的信息。例如，通过CBS播出"The Big Bang Theory"的新剧集，或通过ESPN播出直播足球赛。对于点播内容，例如，这可以是显示HBO "Game of thrones"结果的Prime Video。如果结果项目表示频道上的直播节目( |
列表 |
channel（频道）可选 |
有关当前正在播放视频的频道的信息。 |
对象 |
callSign（频道）可选 |
通过呼叫信号（例如PBS）指定频道。
示例： |
字符串 |
affiliateCallSign（频道）可选 |
通过本地分台呼叫信号（如KCTS9）指定频道。
示例： |
字符串 |
channelMetadata可选 |
提供有关指定频道的其他信息。 |
对象 |
name（频道元数据）可选 |
标识频道的另一个值，例如"FOX"。 | 字符串 |
airingDetails可选 |
此对象包含有关何时播出内容的信息。 |
列表 |
isLiveBroadcast可选 |
内容是否为实时播放。对于实时发生的现场活动，如观看NFL橄榄球比赛，或奥斯卡或艾美奖等颁奖典礼，将此项设置为 对于在初始播放时间之前已拍摄好的内容，将此项设置为 示例： |
布尔值 |
start可选 |
时间窗口的开始时间。 示例： |
ISO 8601格式的字符串。 |
end可选 |
时间窗口的结束时间。 示例： |
ISO 8601格式的字符串。 |
networkDetails可选 |
网络详细信息提供有关节目通过哪个网络播放的信息。例如，通过CBS播出"The Big Bang Theory"的新剧集，或通过ESPN播出直播足球赛。对于点播内容，例如，这可以是显示HBO "Game of thrones"结果的Prime Video。如果结果项目表示频道上的直播节目( |
列表 |
series可选 |
如果此项目是连续剧的一部分，则为有关该连续剧的元数据。应当仅对电视节目填写此信息。如果可用，这里的信息用于向用户呈现提示，例如，“这是'The Big Bang Theory'第1季第4剧集”。 |
对象 |
seasonNumber（连续剧）可选 |
视频的季编号。 示例： |
字符串 |
episodeNumber（连续剧）可选 |
视频的剧集编号。 示例： |
字符串 |
episodeName（连续剧）可选 |
剧集名称。 示例： |
字符串 |
seriesName（连续剧）可选 |
连续剧的名称。 | 字符串 |
absoluteViewingPositionMilliseconds必需 |
基于用户观看历史记录的视频进度偏移量（以毫秒为单位）。如果用户以前观看过，则此项表示某个大于0的偏移量。这用于在结果项目上显示进度条，指示用户之前观看了多少。 示例： |
长型 |