Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

Ring

AWS

文档

Support

My Cases

Console

Fire OS文档

主页

开发

测试

应用发布

盈利

用户参与

设备规格

资源

EMBER最佳实践

重要须知： 目录集成仅可用于部分合作伙伴。

本页从初始规划到持续维护介绍目录集成的推荐做法。遵循这些准则可帮助您避免常见问题、改善内容匹配并维持健康的目录。

规划和设置

本节介绍成功进行目录集成的初始步骤。

了解您的集成时间线

目录集成需要仔细规划。分配两到四周时间进行初始设置：

第1周 - AWS账户设置、S3存储桶配置和IAM角色配置。
第2周 - 测试目录创建、验证和初次提交到暂存环境。
第3–4周 - 错误解决、生产启动和监控。

分配专用资源

目录集成涉及元数据转换、自动化脚本编写和持续监控。确保您的团队可以完成以下领域的工作：

将内容元数据导出并转换为娱乐资源增强元数据桥 (EMBER) 格式。
用于生成和上传目录的脚本自动化。
验证目录、在设备上进行测试并监控引入报告。
配置AWS CLI、管理凭证和设置cron任务。

从暂存环境开始

在提交到生产环境之前，请务必在暂存环境中进行验证，并遵循以下概要步骤：

将测试目录提交到staging/目录。
与您的亚马逊代表一起将测试设备添加到允许列表。
确认内容在设备上正确显示。
在生产启动之前修复所有错误和警告。

上传策略

您上传目录的方式会影响处理速度、风险和可靠性。

谨慎使用完整目录更换

要完全重建您的目录，请在清单文件中使用type="CATALOG_FULL"。这种方法可以删除过时或未引用的实体，但风险更高，因为任何缺失的内容都会被删除。在非高峰时段安排全面更换。

使用增量更新进行定期更改

对于每日或每周更新，请在清单文件中使用type="CATALOG_UPDATE"。增量更新仅包括更改的实体（新建、更新或删除），保留未更改的内容，加快处理速度并降低风险。

了解目录级别操作

除了清单级type (CATALOG_FULL和CATALOG_UPDATE) 外，每个目录元素都有一个控制其内容处理方式的action属性：

upsert（默认）- 添加新实体、更新现有实体并保留其他所有内容。可将此项用于增量更新。
replace - 移除目录中的所有现有实体，并将其替换为提交的内容。请谨慎使用，因为文件中未包含的任何实体都将被删除。

要在不替换整个目录的情况下移除单个实体，请在upsert更新中使用Delete元素。删除分层内容时，在删除父项之前需要先删除子项（删除季之前先删除剧集、删除连续剧前先删除季）。

有关完整参考，包括删除版本控制行为和示例，请参阅删除和目录操作。

自动执行上传流程

手动上传容易出错。创建执行以下步骤的自动化脚本：

从您的内容管理系统 (CMS) 数据库生成目录。
对照XSD自动进行验证。
压缩文件。
假设IAM角色并刷新凭证。
按照正确的顺序上传。
通过cron作业进行安排（建议每天凌晨2:00）。

回滚到已知正常的目录

如果提交目录时引入错误，例如内容缺失、关系中断或元数据不正确，则可以通过使用上次经过验证的目录提交完整替换文件来恢复到以前已知的良好状态。

要回滚您的目录，请执行以下操作：

确定存档中最近经过验证的目录版本。
更新清单文件，将type="CATALOG_FULL"结合新的更高版本号使用。
将存档的目录文件提交到S3路径。
监控引入报告以确认回滚处理没有错误。

为了确保回滚的可靠性，请遵循以下做法：

使用目录时间戳和版本号归档每个成功引入的目录。
将存档存储在一个一致的位置。
在重新提交之前，请根据XSD验证存档的目录。
至少保留三个最近的良好目录以便进行恢复。

提示： 作为上传管道的一部分，自动执行存档步骤。收到干净的引入报告后，将提交的文件复制到您的存档位置。

监控和维护

定期监控可帮助您及早发现问题并保持目录健康。

每天监控引入报告

订阅引入报告电子邮件并执行以下操作：

验证错误数等于零。
查看警告和计划修复。
验证项目数量是否符合预期。
追踪略过的项目。

每周查看目录摘要报告

每日目录摘要报告提供您的目录健康状况的全面视图。可查看以下内容：

当前的所有错误和警告
优化建议
内容质量指标
周之间趋势对比

维持上传频率要求

要求的最小值：

增量更新： 至少每七天一次，否则内容可能会被降低优先级。
完整目录更新： 至少每30天一次，否则该目录可能会被禁止显示。

推荐节奏：

每日： 最新发布、可用性变更、节目表更新
每周： 元数据校正、图像更新
每月： 全面验证和清理

文件组织

始终如一地组织您的目录文件可使提交内容更易于管理和调试。

将大型目录拆分成多个文件

不要创建单一的XML文件。应当按类型或更新频率拆分目录：

按目录类型拆分：movies.xml、tv-shows.xml、schedules.xml
按更新频率拆分：daily-updates.xml、stable-content.xml

将每个压缩文件保持在100MB以下，将提交内容压缩后的总大小保持在10GB以下。

注意： 如果您使用多个文件提交目录，则每个XML文件都必须包含DataCollections根元素和所含元素的相应父级层次结构。引入系统合并来自多个文件的内容。

使用一致的文件命名

在文件名中包含时间戳以进行跟踪。例如：

catalog-movies-20260425-140000.xml.zst
catalog-schedules-20260425-140000.xml.zst
manifest-20260425-140000.manifest

一致的命名可以防止意外覆盖，提供清晰的提交历史记录，并在需要时支持回滚。

按逻辑整理多个目录

当您使用相同类型的多个目录时，请按用途进行整理：

ORIGINAL_CONTENT – 您的原创作品。
LICENSED_CONTENT – 第三方许可的内容。
LOCAL_STATIONS – 本地广播分支机构。
EXTERNAL_STATIONS — TMS或Gracenote Video Data (GVD) 引用的电视台。

ID管理

一致、持久的ID对于内容跟踪和跨目录引用至关重要。

使用持久、有意义的ID

ID在创建后不得更改。选择描述性的永久标识符。

正确示例：

id="MOVIE_AVENGERS_2024"
id="SERIES_FRIENDS"
id="NFL_2025_W01_SEA_SF"

错误示例：

id="Movie 123"（含有空格）
id="temp_id"（非持久）
id="12345"（非描述性）

建立ID惯例

在开始构建目录之前，请记录您的ID模式。亚马逊推荐下表中列出的模式。

实体类型	模式	示例
电影	`MOVIE_{标题}_{年份}`	`MOVIE_AVENGERS_2024`
电视连续剧	`SERIES_{标题}`	`SERIES_FRIENDS`
电视季	`{连续剧ID}_S{##}`	`SERIES_FRIENDS_S01`
电视剧集	`{连续剧ID}_E{##}`	`SERIES_FRIENDS_S01_E01`
体育赛事	`{联赛}_{赛季}_{周}_{球队}`	`NFL_2025_W01_SEA_SF`
电视台	`{呼号}_{网络}_{城市}`	`KIRO_CBS_SEATTLE`

切勿重复使用ID

删除内容后，永久停用其ID。不要为不同的内容重复使用ID。创建用于重制或重启的新ID，并维护ID注册表或数据库。

版本管理

版本控制可以管控系统如何处理增量目录更新并防止无序覆盖。

选择版本控制策略

以下是三种常见的版本控制方法。

顺序（简单）

<Movie id="MOVIE_123" version="1">   <!-- 初始版本 -->
<Movie id="MOVIE_123" version="2">   <!-- 首次更新 -->
<Movie id="MOVIE_123" version="3">   <!-- 第二次更新 -->

时间戳（自动）

<Movie id="MOVIE_123" version="1713622889">   <!-- Unix时间戳 -->
<Movie id="MOVIE_123" version="1713622950">   <!-- 61秒后 -->

混合（可读和自动）

<Movie id="MOVIE_123" version="20260425001">   <!-- 日期 + 序列 -->
<Movie id="MOVIE_123" version="20260425002">

跟踪系统中的版本

维护每个实体的版本历史记录：

将每个实体的当前版本存储在数据库中。
在每次更新之前增加版本。
切勿提交小于或等于当前版本的版本。

内容元数据

本节介绍对内容匹配和客户体验影响最大的元数据字段的推荐做法。

标题和描述

当内容在不同地区有不同的标题时，提供特定地区的标题变体。

<Titles>
    <Title language="en" default="true">The Avengers</Title>
    <Title language="en" territories="GB">Marvel Avengers Assemble</Title>
    <Title language="es">Los Vengadores</Title>
    <Title language="fr">Les Vengeurs</Title>
</Titles>

撰写引人入胜的描述和提要：

描述（50–200个字符）：简洁、引人入胜的摘要。
剧情简介（200–500个字符）：没有剧透的详细情节。
使用正确的语法和拼写。
避免夸大其词的营销。
不要剧透重大剧情转折。

图像

使用符合以下要求的高质量图片：

最低分辨率： HD (1920x1080)。
建议分辨率： 4K (3840x2160)，面向未来需求。
最大文件大小： 10MB。
专业品质，无水印或伪影。

遵循EMBER图像中的图像类别指南。

确保所有图像URL均可公开访问，以便亚马逊的引入系统可以检索它们：

使用公共HTTPS URL。
需要有效的SSL证书。
无需身份验证或标头。
测试URL是否返回HTTP 200。
图像必须全天候可用。

外部ID

外部ID是主要匹配机制。纳入所有可用的外部ID。

<ExternalIds>
    <ExternalId scheme="imdb">tt0076759</ExternalId>
    <ExternalId scheme="tms">MV123456789012</ExternalId>
    <ExternalId scheme="eidr">10.5240/XXXX</ExternalId>
    <ExternalId scheme="asin">B09ABC123</ExternalId>
</ExternalIds>

如果没有外部ID，您的内容可能会：

显示为副本，而不是与现有条目合并。
搜索排名较低。
错过跨服务推荐。

确保使用标准标识符方案。有关支持的标识符方案的完整列表，请参阅外部ID。

类型和关键字

尽可能使用EMBER类型方案。

<Genres>
    <!-- 首选ember_genre方案 -->
    <Genre scheme="ember_genre">ember_genre_action</Genre>
    <Genre scheme="ember_genre">ember_genre_thriller</Genre>

    <!-- 自由格式作为回退 -->
    <Genre language="en">动作</Genre>
</Genres>

将每个节目的类型限制为两到四种。类型过多会导致分类失去辨识度。可以使用子类型（如果可用）。

纳入系列片名称、角色名称、演员姓名、备选标题和常用搜索词的相关关键字。

<Keywords>
    <Keyword language="en">复仇者联盟</Keyword>
    <Keyword language="en">漫威</Keyword>
    <Keyword language="en">超级英雄</Keyword>
    <Keyword language="en">钢铁侠</Keyword>
</Keywords>

不要添加过多或无关紧要的关键字。避免使用诸如“电影”、“视频”或“观看”之类的通用术语。标题中不要重复使用字词。重视质量而非数量。

电视内容层次结构

电视内容需要特定的创建顺序才能保持连续剧、季和剧集之间的有效关系。

按正确的顺序创建实体

请务必按以下顺序创建电视内容： TVSeries，接着是TVSeason，然后是TVEpisode。

<!-- 步骤1： 创建连续剧 -->
<TVSeries id="SERIES_1" version="1">
    <Titles>...</Titles>
</TVSeries>

<!-- 步骤2： 创建季（引用连续剧）-->
<TVSeason id="SERIES_1_S01" version="1">
    <Titles>...</Titles>
    <Relationships>
        <isSeasonOfSeries programRef="SERIES_1" seasonNum="1"/>
    </Relationships>
</TVSeason>

<!-- 步骤3： 创建剧集（参考季和连续剧）-->
<TVEpisode id="SERIES_1_S01E01" version="1">
    <Titles>...</Titles>
    <Relationships>
        <isEpisodeOfSeason programRef="SERIES_1_S01" episodeNum="1"/>
        <isEpisodeOfSeries programRef="SERIES_1" episodeNum="1"/>
    </Relationships>
</TVEpisode>

纳入两个剧集的关系

对于每个TVEpisode，纳入isEpisodeOfSeason和isEpisodeOfSeries。这提供了灵活的导航，并支持连续剧级别和季级别浏览。

评分和内容适当性

内容评分可帮助客户做出明智的观看决定。为提供您的内容的每个地区提供特定于地区的评分。

提供特定于地区的评分

纳入每个地区的相应评分系统和认证。

<Ratings>
    <Rating system="MPAA" certification="PG-13" territories="US">
        <Descriptors>
            <Descriptor code="V">连续暴力与动作镜头</Descriptor>
        </Descriptors>
    </Rating>
    <Rating system="BBFC" certification="12A" territories="GB"/>
    <Rating system="FSK" certification="FSK 12" territories="DE"/>
</Ratings>

使用描述符来提高透明度

通过纳入原因代码（V代表暴力、L代表语言、S代表色情内容）、清晰的描述文字和官方评分板措辞，帮助家长做出明智的决定。

直播活动和安排

直播活动可以通过两种方式呈现，具体取决于您的分发模式。

使用ProgramAiringOffers以进行基于应用的直播

仅在您的应用中直播活动时使用ProgramAiringOffers。在此模型中，用户通过您的应用（并非广播频道）访问活动，并且Airing元素没有stationRef属性。

示例包括您的应用专属的NFL比赛、您的服务专属的音乐会直播、按次付费观看的拳击比赛、电子竞技锦标赛或您的流媒体服务上的剧院表演。

使用ScheduleCatalog进行线性广播

当活动在电视台或频道播出时，使用ScheduleCatalog。在此模型中，任何收看该电视台的人都可以观看该活动，Airing元素具有stationRef属性，并且该活动出现在24小时广播时间表中。

示例包括CBS的NFL比赛、NBC的奥运会或ABC的颁奖晚会。

可以同时使用两者（如果适用）

许多合作伙伴在线性电视及其流媒体应用中直播相同的活动。以下为相关示例：

创建一个SportsEvent节目。
在ScheduleCatalog中引用它以进行线性广播。
在ProgramAiringOffers中引用它以进行应用直播。
每个引用可以有不同的权利、封锁规则和质量等级。

重复使用直播活动进行VOD重播

直播活动结束后，您可以使用相同的节目实体以点播形式提供它。在同一个目录更新中同时提交ProgramAiringOffers和ProgramOffers，以确保从直播到点播的无缝过渡。

活动期间（限时直播）

<ProgramAiringOffers id="AIRING_OFFER_CONCERT_2026" version="1" programRef="CONCERT_2026">
    <ProgramAiringOffer start="2026-06-15T20:00:00Z"
                        end="2026-06-15T23:00:00Z">
        <Airing id="AIRING_CONCERT_2026"
                startTime="2026-06-15T20:00:00Z"
                duration="PT3H"
                programRef="CONCERT_2026">
            <Live/>
            <New/>
        </Airing>
        <Entitlements>
            <Entitlement type="subscription"/>
        </Entitlements>
        <LaunchTargets>
            <LaunchTarget type="FIRETV">
                amzn://apps/watch?id=CONCERT_2026&amp;live=true
            </LaunchTarget>
        </LaunchTargets>
    </ProgramAiringOffer>
</ProgramAiringOffers>

活动结束后（VOD重播无限期可用）

<ProgramOffers id="OFFER_CONCERT_2026" version="1" programRef="CONCERT_2026">
    <ProgramOffer>
        <Entitlements>
            <Entitlement type="subscription"/>
        </Entitlements>
        <VideoResolutions>
            <VideoResolution>4K</VideoResolution>
        </VideoResolutions>
        <LaunchTargets>
            <LaunchTarget type="FIRETV">
                amzn://apps/watch?id=CONCERT_2026&amp;replay=true
            </LaunchTarget>
        </LaunchTargets>
    </ProgramOffer>
</ProgramOffers>

VOD重播通过追溯观看、倒带和暂停功能、无时间限制以及通过不同级别获利的能力来扩展内容价值。

线性目录

如果您发行线性广播内容（电视台、广告变现型免费流媒体电视 (FAST) 频道），亚马逊强烈建议您使用带有TMS或Gracenote电视台ID的ExternalStation引用。

仅当您的原创内容未在外部系统（例如本地作品或自定义FAST频道）中提供时，才使用完全定义的Station元素。使用Station元素创建完全定义的电台时，必须纳入适用的节目表、节目、优惠和策略。

使用外部电视台引用的好处：

无需节目元数据 - 外部系统已经有完整的节目详细信息。
无需提交节目表 - 由TMS或Gracenote提供节目表数据。
自动更新 - 节目和节目表变更由外部提供者处理。
减少维护 - 您只需维护StationOffers（访问权限和权利）。
集成速度更快 - 提交电视台ID和访问规则，而不是成千上万的节目。

您提供的内容：

带有TMS或GVD ID的ExternalStation元素。
StationOffers（权利、地理限制）。

外部提供者处理的内容：

所有节目元数据（标题、描述、图像）。
完整的广播节目表（每天24小时更新）。
节目关系和连续剧层次结构。
评分和内容咨询。

EMBER目录集成概述 - 目录集成过程概述
EMBER规范概述 - 包含目录类型、核心概念和数据类型的架构参考
EMBER示例 - 常见目录场景的XML示例
所有EMBER元素 - 完整的元素目录

Last updated: 2026年5月28日