步骤4： 实现EPG同步任务

电子节目指南 (EPG) 同步任务设计指南

1. 在实现EPG同步任务之前，请查看Vega无头任务和服务。
2. 使用云目录可以实现任务轻量化。
3. 利用getLastCommittedLineupVersion函数来执行轻量化版本检查，如果系统已有最新时间表，则可以跳过引入。提交版本是一个不透明字符串，您可以使用最适合您的任意算法来设置它。它可以是时间表的哈希值、时间戳或其他版本控制策略。
4. 限制任务的内存使用量，以免超出系统阈值或发生终止情况：
   1. 仅下载API集成所需的数据。
   2. 使用HTTP 1.1 Range请求头（RFC 7233，第3节）等方法，以数据块/页面的形式从后端下载数据。
   3. 请勿对EPG数据使用XML模式。在JS中，JSON模式更容易解析，解析时内存效率也更高。
5. 如果由于任何原因导致EPG同步任务因Promise.reject(error) 而失败，则系统将通过指数退避自动最多重试8次。

Vega EPG提供方API指南

1. 为了获得最佳性能和使用最新功能，请使用最新的接口版本。接口名称末尾的后缀是版本号。例如，ProgramLineupProvider2是ProgramLineupProvider的推荐升级版本。所有对接口或API的引用均假定您使用的是最新版本。
2. ChannelLineupProvider接口需要完整的频道时间表，这是当前列表的完全集/替代。
3. LiveEventProvider接口需要完整的直播活动时间表，这是当前列表的完整或替代版本。
4. ChannelLineupProvider、ProgramLineupProvider和LiveEventProvider接口是事务型接口。
   1. 最后必须调用commit API才能完成事务。调用commit()后，无法重复使用该对象。如有必要，必须创建一个新对象。
   2. 在不调用commit的情况下销毁ChannelLineupProvider、ProgramLineupProvider和LiveEventProvider对象，会导致事务中止。
   3. 在更新节目或使用ProgramLineupProvider之前，请提交新的频道时间表（如果需要）。频道和节目更新不能交错。
   4. 如果尚未提交与节目的ChannelDescriptor对应的频道，则ProgramLineupProvider.upsert() 操作将失败。
5. 必须在同一线程上调用各个时间表提供方函数（这些函数不具备线程安全性）。
6. ChannelMetadata.name字段表示频道的营销名称，会显示在Fire TV旋转显示区域中。如果未提供此字段或提供空字符串，则频道引入将失败。Fire TV最多显示25个字母数字字符，如果长度超过此限制，则不会显示完整的频道名称。此最大数目限制适用于半角和全角字符集。示例：
   1. The Walking Dead Universe（最大长度-通过）。
   2. Ed's Purple Plane（最大长度 - 通过）。
   3. How Sally Fell off her Horse and Learned to Play Piano on a Saturday（最大长度 - 未通过，因为长度超过25个字符）。
   4. エドのパープルプレイン（最大长度 - 通过）。
7. 如果使用ProgramLineupProvider，则需要提供至少48小时的节目数据。
8. 当用户升级或降级其订阅套餐时，授权频道和直播活动的数量也会相应变化。为了适应这些变化，请确保在订阅修改期间调用频道、节目和直播活动引入API（分别为ingestChannelLineup()、ingestProgramLineup()和ingestLiveEvents()）。
9. 如果使用ProgramLineupProvider，则必须提供至少48小时的节目数据。
10. 通过ChannelMetadata.logoUrl指定的频道标志必须是尺寸为120x68像素的多色调图像。

错误处理

应捕获数据引入期间发生的所有错误并将其推送到后端。创建警报以确保尽快解决错误。

1. ProgramLineupProvider和LiveEventProvider支持部分成功的提交，并为未能提交的节目和直播活动提供错误反馈。
   1. ProgramLineupProvider的更新和插入以及LiveEventProvider的添加操作会返回未能添加到提交队列的IUpsertProgramFailure或IAddLiveEventFailure对象的列表。如果成功将所有节目或直播活动添加到提交队列中，则返回一个空列表。
   2. 将失败节目和直播活动推送到后端并触发警报，以便在下次同步之前快速解决无效数据问题。
   3. 失败时，中止节目或直播活动引入进程以解决故障，然后重试或只提交成功的节目或直播活动。
2. 如果尝试写入的数据超过提供方分配的存储的大小限制，则在EPG同步任务期间会引发StorageLimitError。
   1. 停止引入，并触发警报。
   2. 如果您遇到此错误，请咨询您的亚马逊联系人。
3. 调用ChannelLineupProvider.add()时，如果有任何提供的频道无效，则会引发InvalidArgumentError。此错误消息包括插入失败的总数和前5个失败频道的原因。
   1. 此错误消息采用以下格式。

      复制代码 已复制到剪贴板。

      在提供的数据中发现一个无效频道，列出部分示例如下：[{"channelIdentifier":"xxx","channelMajorNumber":xx,"channelMinorNumber":xx,"errorMessage": "xxx"}]
      

4. 每个字符串字段都有大小限制。如果字段大小超出限制，则会截断字符串并在其末尾加上“...”，或者抛出InvalidArgumentError。每个字段的详细信息位于EPG提供方接口的内联文档中。
5. 如果由于任何原因导致EPG同步任务因Promise.reject(error) 而失败，则系统将通过指数退避自动最多重试8次。

云目录与设备端引入

如先决条件中所述，亚马逊建议将您的目录与云服务（如亚马逊目录服务或Gracenote）集成。对CDF或Gracenote集成模式加以利用，可以带来多项好处：

• 无需节目时间表引入（这种引入可能会非常庞大且难以解析）。
• 在频道引入期间无需提供除ChannelType之外的频道元数据。将通过云服务自动获得其余频道元数据。
• 可扩展性更强，便于随客户群增长而扩展。

CDF是最直接的集成，能够减少延迟并加快未来功能的启用。请记住，对于每个单独的频道，都必须在以下两者之间做出选择：使用基于云的目录，或是使用设备端节目时间表引入。这意味着可以让一个频道使用Gracenote ID，另一个频道使用CDF，第三个频道使用设备端节目时间表引入。

下面针对Fire TV支持的亚马逊第一方功能，在功能级别上对CDF、Gracenote和设备端节目引入进行了比较。

功能	CDF	Gracenote	设备端节目引入
浏览专用的旋转显示区域
电视直播提供方行	✓	✓	✓
App Peak	✓	✓	✓
浏览混合旋转显示区域
近期观看内容	✓	✓	✓
正在播放主页	✓	✓	✓
类型行	✓	✓	✓
浏览
电子节目指南	✓	✓	✓
搜索
频道	✓	✓	✓
节目	✓	✓
语音
按频道名称调谐	✓	✓	✓
按节目名称调谐（仅限新节目/直播）	✓	✓
节目单刷新方法
通过目录查询自动进行	✓	✓
设备端			✓

提供CDF Station ID（首选）

如果您提供了CDF Station ID，则该信息将通过直播TV应用每天同步到云端。该CDF Station ID将用于在Fire TV目录中查找频道，该目录包含最多14天的节目信息。此信息将显示在Home（主页）和Live（直播）选项卡以及Channel Guide（频道指南）中。它将自动刷新到最新状态，并可通过搜索和Alexa的语音操作功能发现。

如需了解用于此数据源的相应值，请参阅数据类型参考页面的外部ID一节。

提供Gracenote ID

如果提供了Gracenote频道ID（onTV或GVD [全球视频数据]），则该信息将通过直播TV应用每天同步到云端。如果找到了Gracenote ID，该ID将用于在Fire TV目录中查找频道，该目录包含最多14天的节目信息。此信息将显示在Home和Live选项卡以及Channel Guide中。它将自动刷新到最新状态，并可通过搜索和Alexa的语音操作功能发现。

如需了解用于此数据源的相应值，请参阅数据类型参考页面的外部ID一节。

设备端节目引入

如果没有为频道提供CDF Station ID或Gracenote频道ID，请插入以下内容：

• 所有频道元数据
• 您的标志URL
• 使用节目时间表提供方定期插入所有频道中的所有待播节目信息。

Vega示例应用说明了如何完成这一操作。

元数据值

如需了解频道、节目和直播活动的各个元数据字段支持的值，请参阅数据类型参考页面。

频道和直播活动排序

频道排序

频道排序决定Fire TV设备用户界面显示的频道排行。基准顺序由提供方决定。但是，客户可以通过上下文菜单或频道管理器收藏频道。这些频道的显示优先级最高。因此，优先级为：收藏夹 > 频道排序选项。

Fire TV提供以下类型的频道排序：

1. 按字母顺序： Fire TV用户界面中的频道按照name字段的升序顺序显示。这是默认排序。
2. 自定义频道排序： Fire TV用户界面中的频道按照频道引入期间提供的频道元数据的SortRank字段值的顺序显示。如果未提供SortRank，频道则排在最底部。该字段值相同时将按照频道name的字母顺序排序。如果您更喜欢这种排序方式，请通知您的亚马逊联系人。
3. 频道编号排序： Fire TV用户界面中的频道根据提供的频道描述符主要和次要编号按升序显示。频道先按主要编号排序，然后按次要编号排序。例如，频道3.1显示在频道3.10之前。该字段值相同时将按照频道name的字母顺序排序。如果您更喜欢这种排序方式，请通知您的亚马逊联系人。

为了获得一致的体验，请选择与应用内的顺序最接近的频道顺序。在加入进程中，您需要与您的亚马逊联系人合作选择频道排序方法。

直播活动排序

在Fire TV用户界面中，直播活动将根据直播活动引入期间提供的LiveEvent元数据的SortRank字段值，按顺序显示。如果未提供SortRank，则相应的直播活动将排在最底部。如果不同直播活动的该字段值相同，则按直播活动标题的字母顺序显示。请将最重要的内容放在最前面，使其最为显眼。

最大推出速度

以最大500K/小时的速度向客户分阶段推出频道。

此值是指拥有频道权利的客户Fire TV设备的数量。频道权利意味着从Fire TV线性集成UX点击一次即可全屏播放。

示例：

• 应用ABC提供视频点播，但将直播TV作为付费附加程序。费率仅针对拥有电视直播附加程序的ABC客户。
• 应用XYZ提供了一种免费的基础频道套餐和另一种包含更多频道的付费套餐。如果更新了付费套餐的频道时间表，则此费率针对的是使用该付费套餐的客户。

UX字段列表

以下示例说明了在Fire TV UX中，元数据字段如何用于在填充值时提供上下文信息。

UX字段	描述	通过认证的必需项（是/否）	关联的元数据字段
节目名称	节目的名称。这是屏幕左上角的大字号文本。	是	Program.title
播放时间	播出时间（例如： 23:00至24:00）。位于节目名称正下方。	是	Program.startTimeMs Program.endTimeMs
剧集名称	正在播放的剧集的名称。在播放时间和徽标下方以粗体显示。	是	Program.subtitle
剧集描述	剧集的描述。填充剧集名称之后剩余的部分。	是	Program.description
季节和剧集信息	连续剧（如情景喜剧）中常见。提供本次播放的季和剧集信息。这是剧集名称后节目简介的一部分。	否	Program.seriesInfo.season Program.seriesInfo.episode
评级	以徽标形式显示剧集的本地评分。与播放时间位于同一行。	否	Program.ratings
用于徽章的各种属性	请参阅数据类型参考页面的属性一节。	否	Program.attributes
节目图像	填充旋转磁贴的16:9节目/电影图像。分辨率应为768x432或更高。	是	Program.thumbnailUrl
背景图像	填充节目简介旁右上角部分的16:9节目/电影图像。此项分辨率应为1280x720或更高。	是	Program.posterArtUrl
频道名称	旋转磁贴上显示的频道名称。如需有关显示命名限制的指导，请参阅EPG引入最佳实践。	是	ChannelMetadata.name
频道标志	在EPG中使用的120x68多色调图像。如果没有频道标志，则会回退到频道名称（选取框中）。	是	ChannelMetadata.logoUrl 或者，如果您无法在ChannelMetadata中提供标志URL，请联系您的亚马逊联系人提供信息。
频道类型	可将某个类型分配给频道，以便该频道能显示在Fire TV用户界面上的其他入口点中。	否	ChannelMetadata.genres

• 上一步 – 步骤3： 定义您的任务
• 下一步 – 步骤5： 计划EPG同步任务

---

Last updated: 2025年9月30日