您可以使用基于文件的 Feed、Merchant API 或两者的组合将商品数据上传到 Merchant Center：
- 基于文件的商品 Feed：使用 SFTP、Google Cloud Storage、Google 表格或按计划提取功能上传 CSV、TSV 或 XML 文件。
- Merchant API：直接从后端发送程序化请求，以便在商品数据发生变化时进行增量更新，同时定期进行完整目录同步。
本指南比较了这两种方法，说明了何时使用其中一种方法（或同时使用这两种方法），并提供了分步迁移指南，以防您决定将部分或全部商品从文件 Feed 迁移到 API。
选择数据源方法
评估您的目录波动性、后端架构和运营工作流，以决定是使用 Merchant API、文件 Feed 还是混合设置。
何时使用 Merchant API
在以下情况下，请使用 API 主要数据源：
- 直接程序化集成：您更愿意直接从后端调用 API，而不是生成文件和管理文件传输流水线（例如 SFTP 或 Google Cloud Storage）。
- 价格和库存波动较大：您的商品价格或库存水平在一天中频繁变化。
- 在数据发生变化时立即更新：您希望在后端发生商品变化时立即将其发送给 Google，而不是等待下一次预定的文件生成和上传。
- 增量目录更新：您希望在单个商品发生变化时插入、更新或删除该商品，而无需每次都重新上传整个目录。
- 部分属性更新：您希望更新商品的特定字段（例如使用
productInputs.patch更新price或availability），而无需重新发送完整的商品载荷。
何时使用文件 Feed
在以下情况下，请使用基于文件的主要数据源：
- 静态目录：您的商品数据不经常更改（例如，每天一次或更少）。
- 仅快照后端，无增量跟踪：您的后端仅导出完整目录快照，无法跟踪商品级更改或显式商品删除。
- 基于电子表格的工作流：非工程团队直接在 Google 表格或 CSV 文件中精选或替换商品数据。
- 低维护操作：您更倾向于使用预定的文件导出方式，由 Merchant Center 负责提取和快照处理，而不是通过 API 集成来处理请求节奏、重试处理和定期完整目录同步。
何时同时使用
在以下情况下，您可以在同一 Merchant Center 账号中结合使用文件 Feed 和 Merchant API：
- 分区商品清单：您可以使用 Merchant API 处理快速变化的商品（例如闪购或高周转率商品），并使用文件 Feed 处理静态商品清单细分或单独的产品线。确保每件商品仅通过一个主要数据源上传（请参阅并行使用和主要数据源所有权）。
- API 主要数据与基于文件的补充 Feed：您通过 API 主要数据源管理核心商品数据，而非工程团队或第三方合作伙伴则通过基于文件的补充 Feed（例如 Google 表格或 CSV 文件）提供其他属性，并与属性规则结合使用，反之亦然。
- 部分或分阶段迁移：您将特定市场、类别或子账号迁移到 API，同时将目录的其余部分保留在文件 Feed 中。
如果您决定将部分或全部商品从文件 Feed 迁移到 Merchant API，请按照分步迁移指南操作。
主要架构差异
文件 Feed 和基于推送的 Merchant API 在 Google 处理和管理商品数据的方式上有所不同：
| 概念 | 文件 Feed | Merchant API |
|---|---|---|
| 集成模型 | 离线文件转储：您将目录导出到文件，然后使用 SFTP、Google Cloud Storage、Google 表格或按计划提取功能进行传输。 | 直接程序化集成：您的后端直接向 API 端点发送请求。 |
| 变更粒度 | 批量处理：修改一项内容通常需要重新处理整个文件。 | 精细交易：您可以仅插入、修补或删除发生变化的商品。 |
| 同步时间 | 批量同步：更改会在后端等待，直到下一个预定的文件导出和传输周期。 | 立即或定期调用：您可以在增量更改发生时立即发送，同时进行定期完全同步。 |
| 删除行为 | 隐式（快照）：每个文件都是一个完整的快照；从主要文件中移除某一行会删除相应商品。 | 显式：没有快照概念；调用 productInputs.delete 即可移除已停售的商品。 |
| 资源表示 | 单一状态：文件中的行代表原始输入。 | 区分原始数据和处理后的数据：API 会将数据拆分为 ProductInput（原始输入）和 Product（最终处理后的状态）。 |
| 属性（Feed）规则 | 在 Merchant Center 界面中应用于原始文件列。 | Merchant Center 界面支持此功能。将 API 数据与第三方补充文件合并时，此步骤为必选；如果单来源转换在后端处理，则此步骤为可选。 |
并行使用和主要数据源所有权（“最后更新者胜出”）
虽然您可以在同一个 Merchant Center 账号中同时使用文件 Feed 和 API，但我们强烈建议您仅使用一种方法来插入任何给定商品。
Merchant Center 采用“最后更新优先”模式。推送最新商品插入内容的主要数据源（API 或文件 Feed）将获得该商品数据的主要所有权：
- 当文件数据源拥有商品时：在后续文件上传中省略该商品会触发隐式删除，从而从 Merchant Center 中移除该商品。
- 当 API 数据源拥有商品时：在文件上传中忽略该商品不会产生任何影响，因为文件 Feed 不再拥有该商品。您必须调用
accounts.productInputs.delete才能将其移除。 - 意外重新获得所有权的风险：如果更新后的文件 Feed 在 API 推送后运行，并且包含相应商品，则文件数据源会重新获得所有权。随后从文件中省略该商品会导致该商品被意外删除。
为避免意外删除或丢失 API 更新，请勿同时使用 API 和文件主要数据源对同一商品执行并发更新。
API 关键注意事项
在开始实现之前，请先了解以下重要的 Merchant API 行为：
灵活的数据源（不含语言或标签）
与需要您预先定义特定目标 Feed 标签和语言的文件 Feed 不同，Merchant API 允许您在不指定 feedLabel 或 contentLanguage 的情况下创建主要数据源。
- 灵活上传：您可以将具有任意语言或 Feed 标签组合的商品上传到单个数据源。
- 简化管理：您无需为每个目标市场创建和管理单独的数据源。注意：如需详细了解如何选择数据源策略，请参阅选择数据源策略。
同步策略和配额
与文件 Feed（您在其中一次性上传整个目录）不同，您需要围绕增量更新和有节奏的完整同步来设计 Merchant API 集成：
- 将增量更新与定期完整同步相结合：当后端中的商品属性发生变化时，发送
productInputs.insert或productInputs.patch请求。由于仅依赖增量更新可能会导致数据随着时间的推移而不同步，因此您还应定期运行完全同步，以使目录与可信来源保持一致（这也会刷新 30 天的商品过期时间）。运行完整同步的频率取决于目录大小和可用 API 配额。 - 根据 API 配额调整请求节奏：请勿一次性为所有商品调用 API。虽然增量更改可以在发生时发送，但请在一天内均匀分布完整同步请求，以保持在每分钟和每日方法调用配额内。如需了解详情，请参阅配额和限制以及频繁更新商品。
测试集成
在进入生产环境之前，请先在安全的环境中验证集成逻辑。
使用测试账号
在生产环境中进行更改之前，我们建议您在沙盒测试账号中执行迁移的初始步骤：
- 创建测试账号：设置一个独立的测试账号，以便安全地进行实验，而不会影响正在投放的广告或非付费商品详情。
- 创建 API 数据源：练习创建 API 主要数据源。
- 测试属性规则：验证数据转换和补充 Feed 联接。
- 验证载荷和商品密钥：推送示例商品，以验证 SKU 大小写、编码和错误处理。
如需了解详情，请参阅第 1 步：创建测试账号和测试账号指南。
验证产品密钥是否一致
确保您的程序化载荷商品键与文件 Feed SKU 完全一致。Google 通过结合以下信息来识别商品：
offerId（在文件 Feed 中称为id，区分大小写）contentLanguage（例如en）feedLabel（例如US）
特殊字符和编码
如果您的商品标识码包含 /、% 或 ~ 等字符，请在 API 调用中使用编码格式（未填充的 base64url 编码）。如需了解详情，请参阅 ProductInput.name
并发控制
在实时集成中，由于网络延迟，更新可能会不按顺序到达。为防止旧更新覆盖新数据，请使用 ProductInput 资源中的 versionNumber 字段。
分步迁移指南
如果您决定将部分或全部商品从文件 Feed 迁移到 Merchant API，请按照本指南操作，在不丢失展示次数或投放历史记录的情况下完成商品迁移。
1. 在测试账号中演练迁移
在生产环境中进行更改之前，请使用 accounts.createTestAccount 方法创建沙盒化测试账号（请参阅测试账号指南）。测试账号提供了一个隔离的环境，其中商品默认获得批准，无需进行网域验证，并且数据绝不会公开提供。
使用测试账号镜像生产设置，并端到端地演练迁移：
- 镜像商品 Feed 设置：在测试账号中创建文件主要数据源（以及任何补充数据源），并上传正式版 Feed 文件的示例。
- 创建测试 API 数据源和规则：创建 API 主要数据源，并配置任何所需的属性规则或补充 Feed 联接。
- 测试所有权接管和键对齐：针对示例商品发送
productInputs.insert请求，并验证 API 数据源是否接管了现有商品的所有权，而没有创建重复商品。 - 验证更新和删除操作：使用
productInputs.patch测试部分更新，使用productInputs.delete测试移除，并使用products.get检查生成的资源。
2. 创建正式版 API 数据源
在推送数据之前，请在您的账号中创建一个 API 类型的主要数据源。
创建 API 主要数据源
如需创建接受 API 推送的数据源，请向 dataSources 端点发送 POST 请求。如需了解详情，请参阅创建主要商品数据源。
3. 转换自定义属性规则
自定义属性规则会绑定到特定数据源，不会自动从文件数据源转移到新的 API 数据源。
如何转换属性规则取决于其用途：
- 跨来源合并和第三方补充 Feed：如果您将主要 API 数据与外部补充数据源（例如第三方供应商文件、商品目录电子表格或促销信息 Feed）结合使用，则必须在 Merchant Center 界面中重新创建属性规则，并将其附加到新的 API 数据源。客户端预处理无法取代跨多个独立来源联接数据的规则。
- 单来源数据转换：如需对主要目录数据进行单来源清理、默认值设置或字符串格式设置，请在以下选项之间进行选择：
- 后端转换（推荐）：在调用 API 之前，在您自己的系统中应用转换。这样，您就可以更好地进行程序化控制、更轻松地进行测试并简化调试。
- Merchant Center 属性规则：如果您希望 Merchant Center 继续自动管理这些规则，请在 Merchant Center 界面中为新的 API 数据源重新创建转换规则。
4. 启用 API 集成
启用正式版 API 集成，开始在新的 API 主要数据源中插入、更新和删除商品：
插入和更新商品（所有权接管）：从您的集成发送
productInputs.insert和productInputs.patch请求。当您使用 API 插入与现有文件 Feed 商品具有相同键（offerId、contentLanguage、feedLabel）的商品时，API 数据源会获得该商品的所有权并保留其投放历史记录。如需更多指导，请参阅插入商品以及添加和管理商品。删除停产商品：将集成配置为在每次从商品目录中移除商品时显式调用
productInputs.delete。逐步部署：对于大型目录，请一次为一个 Merchant Center 子账号或一个数据源启用集成。
配置并发：如果发送大量请求，请将客户端配置为处理并发请求并管理多个连接。请参阅重构代码以处理并发请求指南。
5. 暂停文件数据源更新
API 集成启用后，请在下次预定的文件运行之前停止文件更新，以免文件数据源覆盖 API 更新：
- 停止向 SFTP/FTP 位置、Google Cloud Storage 或 Google 表格上传新文件。
- 在 Merchant Center 界面中，前往您的文件数据源，然后暂停其按计划提取。
- 由文件数据源拥有的现有商品最多可保留 30 天，直到您的 API 集成插入这些商品。
6. 等待迁移完成并验证
等待所有有效商品从文件数据源迁移到 API 数据源。虽然增量更新会在商品发生变化时迁移商品，但通过常规集成运行有节奏的完整商品目录同步可加快迁移整个商品目录的速度（请参阅同步策略和配额）。
在此阶段：
- 在 Merchant Center 界面中，监控商品数量。请等待文件数据源数量减少到
0，并且 API 数据源数量与有效目录匹配。 - 使用
products.get验证属性和自定义属性规则是否按预期合并。 - 在 Merchant Center 界面中监控 API 诊断工具，以跟踪错误率和 API 性能。
7. 停用文件数据源
转换完成且文件 Feed 项数量为 0 后：
- 确认更新是否实时反映。
- 在 Merchant Center 界面中删除旧版文件数据源，以防止意外的基于文件的更新覆盖您的 API 数据。