开发者控制台
登录
登录
开发者控制台

Discovery接口 (VSK Fire TV)

Discovery接口 (VSK Fire TV)

当用户首次开始使用您的应用时，Alexa会通过Alexa.Discovery接口发送Discover指令，以确定您的视频技能支持哪些功能。您对Discover指令的响应决定了Alexa将向您的Lambda函数发送哪些类型的指令。

例如，如果您指明支持频道更改，则当用户说出“将频道更改为PBS”时，Alexa将发送ChannelController指令。 但是，如果您不指明此项支持，Alexa不会发送指令。

Discover指令

在用户将Alexa技能与其亚马逊账户关联后，Alexa会发送Discover指令；之后，Alexa会定期发送Discover指令以更新任何发现的设备。当您的Lambda函数收到Discover指令时，您无需对其进行处理。

指明Alexa客户端库中的功能

在步骤3： 集成Alexa客户端库中，当您将Alexa客户端库集成到Android项目中时，必须在capabilities数组中指明您的应用支持的功能：

// 创建技能中支持的功能的列表。
List<String> capabilities = new ArrayList<>();
capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);

Alexa将同时查询Alexa客户端库中的这个capabilities列表以及您的Lambda函数，以确定您的应用支持哪些功能。

下文的功能数组部分对这些功能进行了描述。尽管Alexa客户端库和Lambda中定义的功能之间的名称不同，但它们本质大致相同：

客户库功能名称 指令功能名称
AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER Alexa.ChannelController
AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER Alexa.RemoteVideoPlayer
AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER Alexa.PlaybackController
AlexaClientManager.CAPABILITY_SEEK_CONTROLLER Alexa.SeekController
AlexaClientManager.CAPABILITY_KEYPAD_CONTROLLER Alexa.KeypadController

Discover指令示例

除了在初始化Alexa客户端库时指明功能支持外，您还必须在Lambda函数中指明您的视频技能功能。有关创建Lambda函数的详细信息，请参阅步骤6： 创建和部署Lambda程序包。

以下是Alexa发送的Discover指令示例（您的Lambda函数必须处理该指令）。

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "46e09424-9c8a-4868-9db5-6c851e967b32",
            "name": "Discover",
            "namespace": "Alexa.Discovery",
            "payloadVersion": "3"
        },
        "payload": {
            "scope": {
                "token": "[User OAuth Token here]",
                "type": "BearerToken"
            }
        }
    }
}

有效负载描述

下表描述了payload字段。

有效负载描述
字段 描述 数据类型
scope
必需		 请求范围。包括token和type属性。 对象
token
必需		 OAuth2持有者令牌

示例：b68f05cc-6a25-4134

字符串
type
必需		 范围的类型。当前支持的值是 BearerToken。

示例： BearerToken

枚举

响应示例

当您的Lambda收到Discover指令时，您的Lambda必须发回Discover.Response以指明您的技能支持哪些功能。您在capabilities数组中指明此类支持。

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"2aa731f1-b6dd-471c-98fe-3ac5fa5d6554"
    },
    "payload": {
        "endpoints": [
            {
                "capabilities": [
                    {
                        "interface": "Alexa.RemoteVideoPlayer",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PlaybackController",
                        "version": "3",
                        "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous", "Rewind", "FastForward"]
                    },
                    {
                        "interface": "Alexa.SeekController",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "interface": "Alexa.ChannelController",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "interface": "Alexa.KeypadController",
                        "type": "AlexaInterface",
                        "version": "3",
                        "keys": [
                          "INFO", "MORE", "SELECT",
                          "UP", "DOWN", "LEFT", "RIGHT",
                          "PAGE_UP", "PAGE_DOWN", "PAGE_LEFT", "PAGE_RIGHT"
                        ]
                    },
                    {
                        "interface": "Alexa.Launcher",
                        "type": "AlexaInterface",
                        "version": "3.1",
                        "configuration": {
                            "catalogs": [],
                            "targets": [
                            {
                                "name": "profile",
                                "identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw="
                            }, 
                            {
                                "name": "settings",
                                "identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw"
                            }, 
                            {
                                "name": "browse",
                                "identifier": "primevideo.Byb9lM7y5cjvtKF2q1i0samxtKc="
                            }, 
                            {
                                "name": "watchlist",
                                "identifier": "primevideo.OUlgBIlNyZkxB5+MPP+MPo/Yl5Y"
                            }, 
                            {
                                "name": "movies",
                                "identifier": "primevideo.zYYLxEVy5FSUC6oCrza6ly7FWLg"
                            }]
                        }
                    }
                ]
              }
          ]
       }
  }
};

有效负载描述

下表描述了您的响应中的payload对象。

有效负载描述
字段 描述 数据类型
endpoints
必需		 一组终端节点对象，代表与客户的设备云账户关联的设备。 对象
capabilities
必需		 您的技能对终端节点支持的功能接口。有关更多详细信息，请参阅下面的功能对象。 功能对象数组
interface
必需		 描述设备操作的Alexa.Interface的限定名称。

示例： Alexa.RemoteVideoPlayer

字符串
type
必需		 范围的类型。当前支持的值是 BearerToken。

示例： BearerToken

枚举
version
可选		 表示此终端节点支持的接口版本。

示例： 1.0

字符串
cookie
可选		 字符串名称/值对，提供有关设备的其他信息，供技能适配器使用。此属性的内容不能超过5000字节。（亚马逊不使用此字段，客户也不会看到您输入的值。但是，您输入的值不能与视频技能名称相同。）

示例：key1

对象
extraDetail
可选		 cookie对象的密钥。

示例：key1

description
必需		 设备的描述。如果可能，描述应当包含您的公司名称或实现。此值最多可包含128个字符。（亚马逊不使用此字段，客户也不会看到您输入的值。但是，您输入的值不能与视频技能名称相同。）

示例： 亚马逊流媒体应用

字符串
endpointId
必需		 终端节点的标识符。例如，VSKTV。注意：​ 您输入的值不能与视频技能名称相同。还建议您在该值前加上TEST_或PROD_，以确保它与您的视频技能名称不同。

示例： TEST_VSKTV

字符串
friendlyName
必需		 此名称标识了视频技能的实现类型。此值最多可包含128个字符，不应包含特殊字符或标点符号。注意：​ 请勿输入与视频技能名称相同的值。例如，如果您的视频技能名称是“ACME Media”，则不要再输入“ACME Media”作为易记型名称。这样做会导致错误。在名称前加上“TEST_ACME_Media”或“PROD_ACME_Media”之类的内容。

示例： TEST_VSK_FTV

字符串
manufacturerName
必需		 设备制造商的名称。此值最多可包含128个字符。（亚马逊不使用此字段，客户也不会看到您输入的值。但是，您输入的值不能与视频技能名称相同。）

示例： Amazon

字符串

功能数组

capabilities数组可以有一个对象列表，每个对象都包含一个interface、type、version和supportOperations属性。例如，capabilities数组中声明支持播放功能的项目可能如下所示：

{
    "type": "AlexaInterface",
    "interface": "Alexa.PlaybackController",
    "version": "3",
    "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous",
      "Rewind", "FastForward"]
}

Alexa.PlaybackController接口是包含supportedOperations属性的唯一接口。

Alexa.KeypadController接口是包含keys属性的唯一接口。

下表描述了支持的视频技能功能和相关指令：

功能 描述
Alexa.RemoteVideoPlayer 您的技能可以支持来自RemoteVideoPlayer接口的指令，包括SearchAndPlay和SearchAndDisplayResults指令。这些指令让用户可以搜索和播放视频内容。例如，“搜索Breaking Bad”或“Alexa，观看Breaking Bad”。
Alexa.PlaybackController 您的技能可以支持来自Alexa.PlaybackController接口的指令，这些指令用于音频或视频内容的播放、停止和导航播放。例如 “Alexa, fast forward”（Alexa，快进）或 “Alexa, stop”（Alexa，停止）。 请注意，PlaybackController接口还允许supportedOperations属性，如上所示。对supportedOperations允许的属性如下： Play, Pause, Stop, StartOver, Next, Previous, Rewind, FastForward.
Alexa.SeekController 您的技能可以支持来自Alexa.SeekController接口的指令，该接口用于允许用户导航到媒体时间线上的特定位置。例如，“Alexa, fast-forward 60 seconds”（Alexa快进60秒）或 “Alexa, skip back 5 minutes”（Alexa，后退5分钟），而不是“Alexa, fast-forward”（Alexa，快进）或 “Alexa, rewind”（Alexa，倒回）。（如果您的应用只能快进或倒回媒体项目，而不能搜索到时间线上的另一个点，请改为实现PlaybackController接口。）
Alexa.ChannelController 您的视频技能可以支持来自Alexa.ChannelController接口的指令，该接口用于更改或增加娱乐设备的频道。例如，“Alexa, change the channel to PBS”（Alexa，将频道更改为PBS）。
Alexa.KeypadController 您的视频技能可以支持来自Alexa.KeypadController接口的指令，该接口用于向右或向左、向上或向下滚动，或选择聚焦的小组件。例如 "Alexa, scroll right"（Alexa向右滚动）。 按照上面的代码示例列出您的视频技能支持的keys，key值包括以下值： UP、DOWN、LEFT、RIGHT、SELECT、PAGE_UP、PAGE_DOWN、PAGE_LEFT、PAGE_RIGHT、INFO、MORE。有关更多详细信息，请参阅下面的声明KeypadController接口的功能。请注意，KeypadController需要Alexa客户端库版本1.4.5或更高版本。
Alexa.Launcher
仅适用于3.1及更高版本		 您的视频技能可以支持来自Alexa.Launcher 3.1+接口的指令，这些指令可用于导航到技能中的任何标识符/快捷方式。例如，“Alexa，转到观看列表”（当您的视频技能/应用处于打开状态时）。按照示例响应部分来形成快捷方式列表的结构。

声明KeypadController接口的功能

默认情况下，Fire TV提供应用内滚动和选择，如应用内语音滚动和选择中所述。如果您没有在Alexa.Discovery响应中指明支持KeypadController接口功能，VSK会回退到默认的应用内语音滚动和选择功能。

但是，如果您在Discovery响应中明确指明支持KeypadController接口功能，则默认的应用内语音滚动和选择功能将关闭。滚动和选择只会通过您对Lambda收到的KeyStroke指令的响应而发生。

当您声明支持KeypadController时，您需要列出您的视频技能支持的keys： UP、DOWN、LEFT、RIGHT、SELECT、PAGE_UP、PAGE_DOWN、PAGE_LEFT、PAGE_RIGHT、INFO、MORE。如果您声明支持任何key命令，Alexa会假设您正在管理所有key命令的操作。简而言之，您不能声明支持某些key命令，但不支持其他此类命令。例如，如果您不声明UP，Alexa仍会发送带有UP值的keystroke有效负载。默认的应用内语音滚动和选择不会启动以补偿不支持的UP功能。

Last updated: 2022年6月15日