步骤2： 将您的目录上传到暂存环境

本指南涵盖创建、验证您的目录并将其上传到暂存环境。

1.创建您的目录

您提交的目录中的每个文件都必须符合娱乐资源增强元数据桥 (EMBER) 架构。您可以提交包含所有视频元数据的完整目录，也可以提交仅包含更改的增量目录。

目录上传类型

快速开始模板

以下是具有报价的单部电影刚好达到最低要求的有效EMBER目录。

<?xml version="1.0" encoding="UTF-8"?>
<DataCollections schemaVersion="1.0.0">
    <!-- 定义您的节目 -->
    <ProgramCatalog id="MY_CATALOG" version="1">
        <Movie id="MOVIE_001" version="1">
            <ExternalIds>
                <ExternalId scheme="imdb">tt1234567</ExternalId>
            </ExternalIds>
            <Titles>
                <Title language="en" default="true">示例电影</Title>
            </Titles>
            <Descriptions>
                <Description language="en" default="true">
                    一部关于发现和勇气的惊险冒险电影。
                </Description>
            </Descriptions>
            <ReleaseDates>
                <ReleaseDate releaseType="streaming">2024-01-15</ReleaseDate>
            </ReleaseDates>
        </Movie>
    </ProgramCatalog>

    <!-- 定义客户访问内容的方式 -->
    <OfferCatalog id="MY_OFFERS" version="1">
        <ProgramOffers id="OFFER_001" version="1" programRef="MOVIE_001">
            <ProgramOffer>
                <Entitlements>
                    <Entitlement type="free"/>
                </Entitlements>
            </ProgramOffer>
        </ProgramOffers>
    </OfferCatalog>
</DataCollections>

有关完整的架构文档，请参阅EMBER规格概述。

目录创建要求

在创建目录之前，请查看EMBER规格概述中的核心概念，尤其是有关标识符、版本控制、元素排序、本地化和关系的部分。这些规则管理您的目录的构造和处理方式。

要记住的要点：

• ID必须持久（创建后永不更改）、唯一且区分大小写。有关详细信息，请参阅标识符。
• 系统始终使用最高版本号。即使稍后收到较低的版本号，系统也会忽略较低的版本号。有关详细信息，请参阅版本控制。
• 元素排序非常严格。EMBER使用xs:sequence，因此子元素必须按照XSD定义的顺序出现。错误的顺序会导致验证失败。有关详细信息，请参阅元素顺序依赖项。
• 使用BCP-47语言代码和ISO 3166-1地区代码，本地化要求每个可本地化元素刚好一个default="true"条目。有关详细信息，请参阅本地化。
• 关系将电视层次结构（连续剧到季到剧集）联系起来，并将额外内容链接到主要内容。TVSeason必须包含isSeasonOfSeries。TVEpisode必须包含isEpisodeOfSeason或isEpisodeOfSeries。有关详细信息，请参阅关系。

请遵循以下有关文件大小和压缩的指南：

• 使用文件压缩来提高效率。使用GZip (.gz) 或Zstandard (.zst) 格式单独压缩每个数据文件。
• 每个压缩文件的最大大小： 100MB
• 最大总提交大小（压缩）： 10GB
• 如果您的目录压缩后超过100MB，请将其拆分为多个文件（例如，按目录类型或内容类型）。

2.验证您的目录

创建目录文件后，在上传之前在本地对其进行验证。目录引入服务拒绝XML格式不正确或架构验证失败的文件。

下载EMBER XSD架构

下载EMBER架构文件： EMBER XSD文件。将其保存在与您的目录文件相同的目录中。

使用xmllint进行验证

Mac和Linux默认包含xmllint。运行以下命令。

xmllint --noout --schema EMBER_{版本}.xsd your-catalog.xml

预期输出（成功）：

your-catalog.xml通过验证

预期输出（失败）：

your-catalog.xml:42：元素 Movie： 架构有效性错误：
元素“Movie”： 缺少子元素。预期是（标题）。
your-catalog.xml未能通过验证

使用IDE进行验证

大多数IDE都有内置的XML验证：

• Visual Studio Code： 安装Red Hat的XML扩展。键入时出现错误。
• IntelliJ IDEA： 右键单击XML文件，然后选择验证。或者在Settings（设置）> Languages & Frameworks（语言和框架）> Schemas and DTDs（架构和DTD）下进行配置。
• Eclipse： 右键单击XML文件，然后选择验证。

常见验证错误

XML验证会检测以及不会检测的问题

本地验证（xmllint或IDE）检测的问题：

• 格式不正确的XML（损坏的标签、未封闭的元素）
• 架构中未定义的元素和属性
• 缺少的必需元素
• 不正确的元素排序
• 无效的数据类型和格式

本地验证不会检测的问题（引入时检测）：

• 引用完整性。例如，引用了目录中不存在的TVSeason的TVEpisode。
• 业务规则。例如，缺少必需的连续剧关系的TVEpisode (isEpisodeOfSeries)。
• 图像可用性。例如，不可公开访问的图像URL。
• 重复的ID。例如，同一目录中的两个具有相同ID的实体。
• 跨目录引用分辨率。例如，ProgramOffers引用了一个不存在的节目。

3.上传您的目录

验证您的目录后，将其上传到亚马逊为您配置的Amazon S3存储桶。

S3文件夹结构

您的S3存储桶具有以下文件夹结构。

s3://amazon-media-catalogs/<your-provider-prefix>/
├── prod/                          ← 生产环境
│   ├── catalogs/                  ← 在此处上传生产目录文件
│   ├── manifests/                 ← 在此处上传生产清单文件
│   └── reports/                   ← 生产引入报告显示在这里
└── staging/                       ← 暂存环境
    ├── catalogs/                  ← 在此处上传暂存目录文件
    ├── manifests/                 ← 在此处上传暂存清单文件
    └── reports/                   ← 此处显示暂存引入报告

上传工作流程

上传您的目录文件

1. 代入IAM角色。

    aws sts assume-role \
    --role-arn <来自您代表的arn角色> \
    --role-session-name catalog-upload
   

   有关更多详细信息，请参阅代入IAM角色进行目录上传。

2. 按照代入IAM角色来上传目录中所述，将返回的凭证导出为环境变量。
3. 上传目录文件。

    aws s3 cp my-catalog.xml.zst \
    s3://amazon-media-catalogs/<提供者>/staging/catalogs/catalog-20250420-120000.xml.zst
   

4. 上传清单文件。

    aws s3 cp my-manifest.manifest \
    s3://amazon-media-catalogs/<提供者>/staging/manifests/manifest-20250420-120000.manifest
   

   此操作启动引入过程。有关清单文件的详细信息，请参阅上传清单以开始引入。

4.上传清单以开始引入

上传清单文件将启动引入过程。确保仅在上传目录文件后才上传清单。使用以下命令来上传清单文件。

aws s3 cp my-manifest.manifest \
s3://amazon-media-catalogs/<提供者>/staging/manifests/manifest-20250420-120000.manifest

清单文件

清单文件告诉引入服务要处理哪些目录文件。如果上传清单，会立即开始引入。

清单要求

清单文件必须满足以下要求：

• 文件名 - 必须以.manifest结尾（例如catalog_upload_20250420.manifest）
• 格式 - JSON
• 文件名必须是唯一的 - 清单和目录文件名不能覆盖现有文件。使用时间戳或UUID来确保唯一性。

清单格式

以下示例显示了具有单一目录的基本清单文件的结构。

{
    "s3Bucket": "amazon-media-catalogs",
    "s3Keys": [
        "<提供者>/staging/catalogs/catalog-20250420-120000.xml.zst"
    ],
    "type": "CATALOG_FULL",
    "schema": "EMBER"
}

清单字段

下表描述了清单文件中的每个字段。

多文件清单示例

您可以在单个清单中纳入多个目录文件。以下示例引用了三个单独的节目、报价和时间表文件。

{
    "s3Bucket": "amazon-media-catalogs",
    "s3Keys": [
        "<提供者>/staging/catalogs/programs-20250420.xml.zst",
        "<提供者>/staging/catalogs/offers-20250420.xml.zst",
        "<提供者>/staging/catalogs/schedules-20250420.xml.zst"
    ],
    "type": "CATALOG_FULL",
    "schema": "EMBER"
}

系统将s3Keys中列出的所有文件作为单个原子提交进行处理。如果任何文件未通过XML验证，系统将拒绝整个提交。

上传要求

下表汇总了目录上传的要求。

5.查看引入报告

上传目录后，引入系统会处理您的数据并每小时生成报告（前一小时内已处理项目时）。报告是放置在S3存储桶reports/目录中的HTML文件。

通过电子邮件接收报告通知

请让亚马逊代表将您添加到引入报告电子邮件分发列表中。系统会分别发送成功和失败的电子邮件。请求会添加到两个列表中。

该电子邮件提供：

• 前一小时内处理的项目摘要
• 用于下载完整报告的AWS CLI命令

下载报告

当您收到引入报告电子邮件通知时，该电子邮件包含确切的下载命令。将其复制并粘贴到您的终端中。

aws s3api get-object --region us-east-1 \
  --bucket amazon-media-catalogs \
  --key <提供者>/staging/reports/04_20_2025/report-1713622889665-20250420012129.html \
  report.html

您也可以使用以下命令浏览报告目录来访问报告。

# 列出可用报告
aws s3 ls s3://amazon-media-catalogs/<提供者>/staging/reports/

# 下载特定报告
aws s3 cp \
  s3://amazon-media-catalogs/<提供者>/staging/reports/04_20_2025/report-1713622889665.html \
  ./report.html

在网络浏览器中打开report.html以查看完整报告。

理解报告

引入报告包含以下部分。

摘要

摘要显示了总体引入结果，其中包括以下内容：

• 引入ID和时间戳
• 已处理的项目总数
• 计数（添加、更新、删除、未更改和跳过的项目数量）
• 错误、警告和建议消息数量

错误、警告和建议

在报告的这一部分中，展开每个部分，查看单个消息和受影响项目的ID。

• 错误（必须修复）- 系统会跳过有错误的项目，不会引入它们。必须修复这些问题才能显示内容。
• 警告（应修复）- 系统引入了内容，但功能可能有所降低。修复这些问题以获得最佳体验。
• 推荐（可选）- 优化建议，以提高发现和元数据质量。

计数

计数部分提供了添加、删除、更新、未更改和跳过的项目的详细分类。选择Details（详细信息）按钮以查看每个类别中的特定ID。将这些更改与您的预期更改进行比较，以进行最终验证。

目录摘要报告

除了每小时引入报告外，系统每天都会生成目录摘要报告。该报告提供了所有目录提交的整个目录状态的综合视图，包括所有未解决的错误、警告和建议，无论它们是在何时引入的。使用此报告进行持续的目录运行状况监控。

您可以在以下位置找到这份报告：s3://amazon-media-catalogs/<提供者>/prod/reports/<日期>/catalog-summary-<日期时间>.html。

• 上一个 – 步骤1： 设置您的账户
• 下一个 - 步骤3： 在暂存环境中测试您的目录

Last updated: 2026年5月27日