文件导入与数据源
如果客户数据已经存在于其他系统(CRM、财务软件、电子表格)中,就无需等待他们访问网站:直接上传文件即可。导入用于从 CSV 或 Excel 一次性上传档案,数据源则用于定期从网址文件、S3、Google 表格或您的数据仓库中加载档案和事件。
这两个工具都对“所有者”“管理员”和“经理”开放。
从 CSV 和 Excel 导入档案
在菜单中打开数据 → 档案导入,或点击档案页面顶部的档案导入。
文件要求
- CSV 或 Excel 文件(.xlsx、.xls,第一个工作表),第一行为列标题。
- 分隔符可以是逗号、分号或制表符,系统会自动识别。
- 文件大小:CSV 不超过 20 MB,Excel 不超过 10 MB。
- 至少包含一个标识符列:您系统中的客户 ID、邮箱或电话。
- Excel 中日期格式的单元格按
2026-10-28 18:42:00的形式载入,公式按其值载入。不支持 Excel 95 文件和受密码保护的文件:请另存为 .xlsx 或 CSV。
示例:
email;phone;first_name;city;customer_id;bonus
[email protected];+86 138 0013 8000;Anna;Shanghai;1001;350
如何上传
- 点击选择文件并选择文件。
- 表格中会显示文件的列、示例值和目标字段。为每一列指定:
- 身份标识:User ID、邮箱、手机号或匿名 ID:系统据此查找或创建档案。每种类型只能选择一次。
- 属性:档案的一项特征;在旁边用拉丁字母填写键,例如
city或bonus_balance。 - 跳过:该列不导入。
- 点击开始导入。
OneTrace.pro 会根据标题自动建议目标:email 对应邮箱,phone 和 mobile 对应手机号,customer_id 和 user_id 对应 User ID。其他标题会转换为属性键(小写字母加下划线),例如 First name、Last name、City 和 Country 会分别变为 first_name、last_name、city 和 country 属性。中文标题无法自动转换为键,请为其手动填写键。开始导入前请检查这些建议。

导入进度
导入在后台进行:页面上会显示进度条、状态和计数“已处理 N/M,错误:K”。您可以关闭页面,导入会继续进行。出错的行会连同行号一起列出。导入完成后,打开档案按钮会跳转到档案列表。
右侧的历史记录模块显示最近 20 次导入:文件、上传者和上传时间、状态(“已上传”“排队中”“处理中”“已完成”“失败”)以及结果。

行的处理方式
- 如果已存在具有相同标识符的档案,该档案会被更新:新属性会被添加,同名属性会被覆盖。如果一行中出现了两个不同档案的标识符,这两个档案会被合并,参见档案。
- 空单元格会被跳过,不会清除已有的值。
- 数字和
true/false会分别保存为数字和布尔值。 - 文件中的邮箱和电话既会成为档案的标识符,也会成为档案属性。
- 电话号码中的空格、括号和连字符会被去除。请带国家代码填写:
+86 138 0013 8000。不带国家代码的号码(例如138 0013 8000)会以错误的国家代码保存。 - 没有任何有效标识符的行会被跳过并记为错误。
导入会为每一行生成一个 $identify 事件,因此属性变更可能会触发以属性变更为触发器的旅程。如果不希望这样,请在导入期间暂停这些旅程。
数据源
数据源是按计划定期执行的导入。适用于 CRM 或仓库系统每晚生成最新导出文件的场景:OneTrace.pro 会自动获取文件,并更新档案或添加事件。
准备工作
首先在集成板块中创建连接(需要“管理员”或“所有者”角色):
- 网址文件:通过 HTTP(S) 地址获取的文件。如果文件受保护,请填写授权请求头,例如
Bearer加令牌。 - S3 中的文件:AWS、Yandex Object Storage、MinIO 及其他兼容存储的存储桶。
- Google 表格:使用 Google 服务账号密钥访问。请将表格以只读权限共享给该账号。
- PostgreSQL、ClickHouse、BigQuery 或 Snowflake:您数据仓库中的表或查询,参见数据仓库。
文件格式:CSV、JSON(对象数组,不超过 50 MB)和 JSON Lines。
如何创建数据源
- 打开数据 → 数据源,点击新建数据源。
- 填写名称并选择连接。
- 填写连接设置:文件网址和格式、存储桶中的文件路径,或表格 ID 和范围(例如
Sheet1!A:F)。 - 点击加载列,OneTrace.pro 会读取前几行。
- 在导入为字段中选择档案(每一行更新档案属性)或事件(每一行是一个事件)。
- 选择计划:从每 15 分钟到每天一次。
- 在列表格中为每一列指定目标,与 CSV 导入相同。
- 点击保存。

对于事件,列表格中还有事件名称、事件属性和事件时间。时间列为必填项。可以在事件名称字段中为所有行设置统一的事件名称(例如 order_completed),或选择记录事件名称的列。
对于门店小票,有线下小票模板和示例文件:它会填入购买事件、线下购买属性以及各列的提示:电话、会员卡、门店、小票号、金额和商品。参见门店与线下销售。
数据源的运行
数据源卡片上显示状态(“正常”“已暂停”“失败”)、计划、上次运行时间和结果:行数、已接收、已跳过、失败。
- 立即运行:额外运行一次。它也会让数据源从暂停或失败状态恢复。
- 暂停 / 恢复:停止或继续按计划运行。
- 历史记录:运行列表,包括开始时间、触发方式(“按计划”或“手动”)、状态以及带行号的前几个行错误。

注意事项
- 如果文件自上次运行以来未发生变化,运行将以“无变化”状态结束,不会读取任何行。
- 一天内重复出现的同一行不会产生重复数据。
- 对于事件,系统会记住最后加载的事件时间:后续运行会跳过不晚于该时间的行。因此,历史文件只需在末尾追加即可。
- 出错的数据源会按计划重试,错误信息显示在卡片上。
- 已加载的事件计入套餐的每月配额。
- 删除数据源后,已加载的数据会保留。
数据仓库
如果档案和订单已经汇集在您的数据仓库(PostgreSQL、ClickHouse、BigQuery 或 Snowflake)中,数据源可以直接从中读取。每次运行只获取自上次以来发生变化的行,因此即使是大表也无需导出为文件。变更会写入档案和事件,并据此触发旅程、重新计算分群。反方向的操作是导出到数据仓库。
从数据仓库读取在“企业版”套餐中提供,参见套餐。
连接
在集成板块的数据源分组中创建连接。字段与导出到该数据仓库时相同,但最好单独创建一个只读用户:
- PostgreSQL:主机、端口、数据库,以及对所需表拥有
SELECT权限的用户。 - ClickHouse:HTTP 接口地址,以及拥有读取权限的用户。
- BigQuery:拥有 BigQuery Data Viewer 和 BigQuery Job User 角色的服务账号密钥、项目和数据位置。
- Snowflake:账户、使用密钥对的用户、拥有
SELECT权限的角色,以及用于计算的 warehouse。读取时不需要 S3 存储桶。
数据仓库必须可从互联网访问:OneTrace.pro 不会访问内网地址。
数据源设置
按上文所述创建数据源,并选择数据仓库连接。其设置如下:
- 读取内容:表(例如
public.customers或shop_dwh.customers)或自定义查询,即单条SELECT或WITH命令,不带;。OneTrace.pro 会为查询添加条件、排序和行数上限,因此无法通过查询修改数据。 - 游标列:行的修改时间,例如
updated_at。每次运行读取该时间晚于上次运行的行。没有该时间的行不会被读取。 - 行键:唯一列,例如
id或customer_id。用于区分修改时间相同的行。 - 删除标记列:可选,例如
is_deleted。参见删除。

其余步骤与文件相同:加载列、列映射、档案或事件、计划。
如何读取变更
- 首次运行读取整张表,之后的运行只读取在上次读到的行之后发生变化的行。
- 每次运行最多读取 100 万行。如果行数更多,下一次运行会立即开始,无需等待计划,因此大表的首次加载会连续分多次运行完成。
- 如果运行中断,相同的行会被重新读取:档案只是再更新一次,重复的事件不会产生重复数据。
- 更改表、查询、游标列或行键后,会从头开始读取。
- 修改时间列必须由您的数据仓库更新:时间没有变化的行,OneTrace.pro 不会重新读取。
- 查询以只读方式执行,并有时间限制:PostgreSQL、ClickHouse 和 Snowflake 为 10 分钟,BigQuery 为 15 分钟。
删除
如果档案数据源某一行的删除标记列为 true 或 1,OneTrace.pro 会删除带有该行标识符的档案,与 GDPR 请求的处理相同:连同历史记录、合并的档案以及导出中的数据一起删除。删除会记录在审计日志中,运行结果会显示删除了多少个档案。在事件数据源中,带标记的行会被直接跳过。
如需连同历史数据一次性从 Mindbox 等平台迁移,可使用专门的工具,参见从其他平台迁移。