电子节目指南 (EPG) 同步任务设计指南
- 在实现EPG同步任务之前，请查看Vega无头任务和服务。
- 使用云目录可以实现任务轻量化。
- 利用
getLastCommittedLineupVersion函数来执行轻量化版本检查，如果系统已有最新时间表，则可以跳过引入。提交版本是一个不透明字符串，您可以使用最适合您的任意算法来设置它。使用时间表的哈希值、时间戳或其他版本控制策略。 - 限制任务的内存使用量，以免超出系统阈值或发生终止情况：
- 仅下载API集成所需的数据。
- 使用HTTP 1.1 Range请求头（RFC 7233，第3节）等方法，以数据块/页面的形式从后端下载数据。
- 请勿对EPG数据使用XML模式。在JS中，JSON模式更容易解析，解析时内存效率也更高。
- 如果由于任何原因导致EPG同步任务因
Promise.reject(error)而失败，则系统会通过指数退避最多重试8次。
Vega EPG提供方API指南
- 为了获得最佳性能和使用最新功能，请使用最新的接口版本。接口名称末尾的后缀就是版本。例如，
ProgramLineupProvider2是ProgramLineupProvider的推荐升级版本。所有对接口或API的引用均假定您使用的是最新版本。 ChannelLineupProvider接口需要完整的频道时间表，这是当前列表的完整/替代版本。LiveEventProvider接口需要完整的直播活动时间表，这是当前列表的完整或替代版本。ChannelLineupProvider、ProgramLineupProvider和LiveEventProvider接口是事务型接口。- 最后调用
commitAPI来完成事务。调用commit()后不能重复使用该对象。如有必要，创建新对象。 - 在不调用
commit的情况下销毁ChannelLineupProvider、ProgramLineupProvider和LiveEventProvider对象，会导致事务结束。 - 在更新节目或使用
Commit之前，请对新的频道时间表调用ProgramLineupProvider（如果需要）。您不能交错频道和节目更新。 - 如果尚未提交与节目的
ChannelDescriptor对应的频道，则ProgramLineupProvider.upsert()操作会失败。
- 最后调用
- 在同一个线程上调用时间表提供方函数，因为它们不具备线程安全性。
ChannelMetadata.name字段表示Fire TV旋转显示区域中频道的营销名称。如果未提供ChannelMetadata.name，或者提供了空字符串，则频道引入失败。Fire TV最多显示25个字母数字字符，如果长度超过此限制，则不会显示完整的频道名称。此最大数目限制适用于半角和全角字符集。示例：- The Walking Dead Universe（最大长度-通过）。
- Ed’s Purple Plane（最大长度 - 通过）。
- How Sally Fell off her Horse and Learned to Play Piano on a Saturday（最大长度 - 未通过，因为长度超过25个字符）。
- “エドのパープルプレイン”（最大长度 - 通过）。
- 要通过
ProgramLineupProvider引入设备端节目，请联系您的亚马逊联系人，确定要推送多少天的节目，以避免存储限制错误。这取决于您有多少频道和节目。 - 当用户升级或降级其订阅套餐时，授权频道和直播活动的数量也会相应变化。为了适应这些变化，请确保在订阅修改期间调用频道、节目和直播活动引入API。分别包括
ingestChannelLineup()、ingestProgramLineup()和ingestLiveEvents()。 - 使用120x68像素的多色调图像通过
ChannelMetadata.logoUrl指定频道标志。
错误处理
捕获数据引入期间的所有错误并将其推送到您的后端。创建警报以确保尽快解决错误。ProgramLineupProvider和LiveEventProvider支持部分成功的提交，并为未能提交的节目和直播活动提供错误反馈。ProgramLineupProvider更新和插入以及LiveEventProvider添加操作会返回未添加到提交队列的IUpsertProgramFailure或IAddLiveEventFailure对象的列表。如果成功将所有节目或直播活动添加到提交队列中，则系统会返回一个空列表。- 将失败节目和直播活动推送到后端并触发警报，以便在下次同步之前快速解决无效数据问题。
- 失败时，停止节目或直播活动引入进程以解决故障，然后重试或只提交成功的节目或直播活动。
- 如果尝试写入的数据超过提供方分配的存储的大小限制，则在EPG同步任务期间
StorageLimitError会引发错误。- 停止引入，并触发警报。
- 如果您遇到此错误，请咨询您的亚马逊联系人。
- 调用
ChannelLineupProvider.add()时，如果有任何提供的频道无效，则InvalidArgumentError会引发错误。此错误消息包括插入失败的总数和前5个失败频道的原因。-
此错误消息采用以下格式。
-
此错误消息采用以下格式。
- 每个字符串字段都有大小限制。如果字段超过限制，则系统会截断该字符串并在末尾添加“…”，否则
InvalidArgumentError会引发错误。每个字段的详细信息位于EPG提供方接口的内联文档中。 - 如果由于任何原因导致EPG同步任务因
Promise.reject(error)而失败，则系统将通过指数退避自动最多重试8次。
云目录与设备端引入
如先决条件中所述，亚马逊建议将您的目录与云服务（如亚马逊目录服务或Gracenote（仅提供英文版））集成。对亚马逊目录格式或Gracenote集成模式加以利用，可以带来多项好处：- 它无需大型或难以解析的节目时间表引入。
- 在频道引入期间无需提供除ChannelType之外的频道元数据。其余部分由云服务自动获取。
- 可扩展性更强，便于随客户群增长而扩展。
提供亚马逊目录电视台ID（首选）
如果您提供了亚马逊目录电视台ID，则该信息通过直播TV应用每天同步到云端。这些电视台ID提供了一种查找频道的方法。Fire TV目录包含长达14天的节目信息，这些信息显示在“Home”（主页）和“Live”（直播）选项卡以及频道指南中。它会自动刷新到最新状态，并可通过搜索和Alexa的语音操作功能发现。 如需了解用于此数据源的相应值，请参阅数据类型参考页面的外部ID一节。提供Gracenote ID
如果提供Gracenote频道ID（“onTV”或GVD（全球视频数据）），信息会通过直播TV应用每日同步到云端。如果存在Gracenote ID，则用户可以在Fire TV目录中查找具有该ID的频道。该目录包含长达14天的节目信息，这些信息显示在“Home”和“Live”选项卡以及频道指南中。它会自动刷新到最新状态，并可通过搜索和Alexa的语音操作功能发现。 如需了解用于此数据源的相应值，请参阅数据类型参考页面的外部ID一节。设备端节目引入
如果没有为频道提供亚马逊目录电视台ID或Gracenote频道ID，请插入以下内容：- 所有频道元数据
- 您的标志URL
- 使用节目时间表提供方定期插入所有频道中的所有待播节目信息。
元数据值
如需了解频道、节目和直播活动的各个元数据字段支持的值，请参阅数据类型参考页面。频道和直播活动排序
频道排序
频道排序决定Fire TV设备用户界面显示的频道排行。基准顺序由提供方决定。但是，客户可以通过上下文菜单或频道管理器收藏频道。这些频道的显示优先级最高。因此，优先级为：收藏夹 > 频道排序选项。 Fire TV提供以下类型的频道排序：- 按字母顺序： Fire TV用户界面中的频道基于
name字段按照升序顺序显示。这是默认排序。 - 自定义频道排序： Fire TV用户界面中的频道按照频道引入期间提供的频道元数据的
SortRank字段值的顺序显示。如果开发者不使用SortRank，则频道会位于底部。该字段值相同时会按照频道name的字母顺序排序。如果您更喜欢这种排序方式，请通知您的亚马逊联系人。 - 频道编号排序： Fire TV用户界面中的频道根据提供的频道描述符主要和次要编号按升序显示。频道先按主要编号排序，然后按次要编号排序。例如，频道3.1显示在频道3.10之前。该字段值相同时会按照频道name的字母顺序排序。如果您更喜欢这种排序方式，请通知您的亚马逊联系人。
直播活动排序
在Fire TV用户界面中，直播活动会根据直播活动引入期间提供的LiveEvent元数据的SortRank字段值，按顺序显示。如果开发者不使用SortRank，则直播活动会位于底部。如果不同直播活动的该字段值相同，则按直播活动标题的字母排序。请将最重要的内容放在最前面，使其最为显眼。
最大推出速度
以最大500K/小时的速度向客户分阶段推出频道。 此值是指拥有频道权利的客户Fire TV设备的数量。频道权利意味着从Fire TV线性集成UX点击一次即可全屏播放。 示例：- 应用ABC提供视频点播，但将直播TV作为付费附加程序。费率仅针对拥有电视直播附加程序的ABC客户。
- 应用XYZ提供了一种免费的基础频道套餐和另一种包含更多频道的付费套餐。如果更新了付费套餐的频道时间表，则此费率针对的是使用该付费套餐的客户。
