开发者控制台

GetPlayableItemsMetadata指令(VSK Echo Show)

GetPlayableItemsMetadata指令(VSK Echo Show)

一旦Alexa收到您的Lambda对GetPlayableItems的响应,VideoContentProvider API会立即发送GetPlayableItemsMetadata指令作为后续指令,以获取GetPlayableItems中返回的项目的元数据。

下图显示了Alexa指令和Lambda响应。

GetPlayableItemsMetadataItems指令和Lambda GetPlayableItemsMetadataResponse

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-asdfmediaIdentifier的元数据。仅对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 specificationifa属性。其格式设定为版本4 UUID字符串,由短横分隔(8-4-4-4-12)。示例: E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367 字符串
limitAdTracking 指明客户是否希望接收基于兴趣的广告。当客户选择退出基于兴趣的广告时,设置为truelimitAdTracking属性映射至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应仅包含播放和在播放视频之前呈现任何成功提示所需的元数据信息。尽管GetPlayableItemsMetadataResponseGetDisplayableItemsMetadataResponse高度相似,但GetPlayableItemsMetadataResponse包含playbackContextToken。此令牌包含Alexa将传递给您的网页播放器的标识符。playbackContextToken是您选择的与您的媒体关联的标识符。

Alexa将playbackContextToken发送给您的网页播放器,您的网页播放器可以将标识符转换为播放URL。在步骤4: 了解您的网页播放器如何获取媒体播放URL中解释了该过程。在上面的代码示例中,playbackContextToken是一个字符串化对象(一个由streamUrltitle参数组成的键值对),因为这是示例网页播放器所期望的格式:

"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”。



示例Interstellar

字符串

可选


contentType
必需

ContentType指定搜索结果中返回的视频的内容类型。如果发送录制的电影或电视节目,则将contentType设置为RECORDING。如果结果包含有关直播电视节目的信息,则将contentType设置为LIVE。如果结果包含点播内容,则将contentType设置为ON_DEMAND

ContentType还用于向用户呈现提示。例如,当contentTypeLIVE时,Alexa会提供相应提示,例如“这是CBS正在直播的奥斯卡颁奖典礼”。 如果contentTypeRECORDING,Alexa会提供相应提示,例如“这是奥斯卡颁奖典礼”。



示例RECORDINGLIVEON_DEMAND

枚举
playbackContextToken
必需

允许将实体映射回系统以进一步识别的令牌。您可以发送任何字符串标识符,只要您可以将其映射回去以标识您这边的实体即可。此令牌对Alexa来说是不透明的,并发送到设备用于播放。它可以是用于获取元数据信息的相同媒体标识符(如果该元数据信息是播放所需的),也可以是具有播放所需附加信息的不同序列化字符串。

注意:​ 如果您使用示例网页播放器,则playbackContextToken必须是转换为字符串的JSON对象。对象必须包含streamUrltitle键值对。有关详情,请参阅步骤4: 了解您的网页播放器如何获取媒体播放URL

不透明字符串
parentalControl
必需

家长监护信息基于用户和视频。

对象
pinControl
必需

此字段指明,基于设置对于此视频用户是否需要家长监护。这是具有2个值的枚举。

  • REQUIRED: 这意味着家长监护将根据用户的设置应用于此项目。设置此选项后,项目上会显示一个锁定图标,提示此项目应用了家长监护,并且用户需要输入PIN才能观看视频。
  • NOT_REQUIRED: 这意味着家长监护将根据用户的设置不应用于此项目。



示例REQUIREDNOT_REQUIRED

枚举
networkDetails
可选

网络详细信息提供有关节目通过哪个网络播放的信息。例如,通过CBS播出"The Big Bang Theory"的新剧集,或通过ESPN播出直播足球赛。对于点播内容,例如,这可以是显示HBO "Game of thrones"结果的Prime Video。如果结果项目表示频道上的直播节目(contentType = LIVE),则该对象包含其元数据。

列表
channel(频道)
可选

有关当前正在播放视频的频道的信息。

对象
callSign(频道)
可选
通过呼叫信号(例如PBS)指定频道。

示例: PBS

字符串
affiliateCallSign(频道)
可选
通过本地分台呼叫信号(如KCTS9)指定频道。

示例: KCTS9

字符串
channelMetadata
可选

提供有关指定频道的其他信息。

对象
name(频道元数据)
可选
标识频道的另一个值,例如"FOX"。 字符串
airingDetails
可选

此对象包含有关何时播出内容的信息。

列表
isLiveBroadcast
可选

内容是否为实时播放。对于实时发生的现场活动,如观看NFL橄榄球比赛,或奥斯卡或艾美奖等颁奖典礼,将此项设置为true

对于在初始播放时间之前已拍摄好的内容,将此项设置为false。例如,每周四播出的Big Bang Theory的新剧集。对于曾经实时流式播放但现在不再实时播放的内容(如过去的橄榄球比赛),也必须将此项设置为false



示例truefalse

布尔值
start
可选

时间窗口的开始时间。



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

ISO 8601格式的字符串。
end
可选

时间窗口的结束时间。



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

ISO 8601格式的字符串。
networkDetails
可选

网络详细信息提供有关节目通过哪个网络播放的信息。例如,通过CBS播出"The Big Bang Theory"的新剧集,或通过ESPN播出直播足球赛。对于点播内容,例如,这可以是显示HBO "Game of thrones"结果的Prime Video。如果结果项目表示频道上的直播节目(contentType = LIVE),则该对象包含其元数据。

列表
series
可选

如果此项目是连续剧的一部分,则为有关该连续剧的元数据。应当仅对电视节目填写此信息。如果可用,这里的信息用于向用户呈现提示,例如,“这是'The Big Bang Theory'第1季第4剧集”。

对象
seasonNumber(连续剧)
可选

视频的季编号。



示例1

字符串
episodeNumber(连续剧)
可选

视频的剧集编号。



示例3

字符串
episodeName(连续剧)
可选

剧集名称。



示例4

字符串
seriesName(连续剧)
可选
连续剧的名称。 字符串
absoluteViewingPositionMilliseconds
必需

基于用户观看历史记录的视频进度偏移量(以毫秒为单位)。如果用户以前观看过,则此项表示某个大于0的偏移量。这用于在结果项目上显示进度条,指示用户之前观看了多少。



示例1248625

长型