Skip to main content

文件上传集成

ACP的Product Feed文件上传采用SFTP推送模式(push-based)。商家主动将商品数据文件推送到OpenAI指定的SFTP服务器,而非由OpenAI来拉取。

3.1 SFTP推送模式

关键点: 这是单向推送。商家掌控上传时间和频率,OpenAI不会主动从商家系统拉取数据。 SFTP凭证在商家获得合作伙伴审批后由OpenAI提供。

3.2 支持的文件格式

编码要求: 所有文本文件必须使用UTF-8编码 Parquet配合zstd压缩是首选方案,因为:
  • 列式存储天然支持高效的字段级读取
  • zstd压缩比高于gzip,解压速度更快
  • 内置schema信息,减少类型歧义

3.3 快照类型:全量覆盖

ACP文件上传采用**全量快照(Full Catalog)**模式,而非增量模式(delta)。 每次上传的文件代表商品目录的完整真实状态(complete source of truth)。这意味着:
  • 上传文件包含所有在售商品的完整信息
  • 每次上传会完全覆盖上一次的数据
  • 不需要标记”新增”、“修改”、“删除”等操作类型
  • 如果某个商品不在最新快照中,它会被视为已下架

3.4 分片策略

大型商品目录需要分片上传。分片规则: 分片示例:
分片时确保每个商品(包括其所有Variant)完整地在同一个分片文件中。不要将同一个Product的不同Variant拆分到不同文件。

3.5 上传频率

推荐方案: 每日凌晨上传一次完整的SFTP全量快照,白天通过REST API推送实时变化(价格调整、库存变动、新品上架)。 这种双通道策略确保:
  • 全量快照提供数据一致性的基线
  • API增量更新保证数据时效性
  • 即使API出现短暂问题,全量快照也能在次日修正

3.6 文件命名规则

使用稳定一致的文件名。每次上传同名文件会覆盖上次的内容。
不要追加(append)。ACP期望文件名稳定,内容覆盖。如果使用带时间戳的文件名,旧文件不会自动清理,可能导致数据混乱。

3.7 商品下架处理

在全量快照模式下,有两种方式下架商品: 方式1: 从快照中省略 最简单的方式。下次上传的快照中不包含该商品,它就自然消失。 方式2: 设置 is_eligible_searchfalse 在快照中保留商品记录,但将 is_eligible_search 字段设为 false。商品数据仍然存在,但不会在ChatGPT的商品发现中出现。
方式2适用于需要保留商品记录但暂时不展示的场景(如季节性商品、临时缺货)。

3.8 Feed Header

每个上传文件必须包含Feed Header信息,标识数据来源和目标:

3.9 最佳实践清单


下一章: 第4章:REST API集成 — Product Feed REST API完整参考