github-actions[bot]
cd73088be6
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
268 lines
8.3 KiB
Plaintext
268 lines
8.3 KiB
Plaintext
---
|
||
title: 准备您的 CSV 文件
|
||
description: 完整的分步指南，指导您将数据格式化以导入 Twenty。
|
||
---
|
||
|
||
## 概览
|
||
|
||
本指南将引导您准备 CSV 文件，以成功完成导入。 请按照以下步骤操作以避免错误。
|
||
|
||
## 步骤 1：检查文件要求
|
||
|
||
开始之前，请确保您的文件满足以下要求：
|
||
|
||
| 要求 | 详情 |
|
||
| -------- | ----------------- |
|
||
| **格式** | CSV、XLSX 或 XLS |
|
||
| **大小限制** | 每个文件最多 10,000 条记录 |
|
||
| **编码** | 建议使用 UTF-8 |
|
||
| **结构** | 每个文件仅一种对象类型 |
|
||
|
||
<Note>对于超过 10,000 条记录的数据集，请拆分为多个文件，或使用[API 导入](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)。</Note>
|
||
|
||
## 步骤 2：下载示例文件
|
||
|
||
**这是最重要的一步。** 示例文件展示了 Twenty 期望的准确列名和格式。
|
||
|
||
1. 进入对象视图（人员、公司等）
|
||
2. 点击 **⋮** → **导入记录**
|
||
3. 点击 **下载示例文件**
|
||
4. 将此文件用作模板
|
||
|
||
<Note>**专业提示：** 改为导出少量现有记录。 这将为您提供数据应如何格式化的真实示例，并且在导入过程中列名会自动映射。</Note>
|
||
|
||
## 步骤 3：移除重复值
|
||
|
||
Twenty 会对某些字段强制唯一性。 重复项会导致导入错误。
|
||
|
||
| 对象 | 唯一字段 |
|
||
| --------- | ------------------ |
|
||
| **人员** | `id`, `email` |
|
||
| **公司** | `id`, `domain` |
|
||
| **自定义对象** | `id`，以及任何您标记为唯一的字段 |
|
||
|
||
**导入之前：**
|
||
|
||
1. 按唯一字段（email 或 domain）对电子表格排序
|
||
2. 删除或合并重复的行
|
||
3. 检查 Twenty 中是否已存在重复项
|
||
|
||
<Warning>**软删除的记录计入唯一性。** 位于“命令菜单 → 查看已删除的记录”中的记录会导致重复错误。 请永久删除这些记录，或将其恢复并更新。</Warning>
|
||
|
||
## 步骤 4：正确格式化各字段类型
|
||
|
||
不同的字段类型需要特定格式。 以下是完整参考：
|
||
|
||
### 文本字段
|
||
|
||
* 无需特殊格式
|
||
* 首尾空格将自动去除
|
||
|
||
### 电子邮件字段
|
||
|
||
* 必须是有效的电子邮件格式：`name@domain.com`
|
||
* 必须唯一（文件内及 Twenty 中不得重复）
|
||
* 对于附加电子邮件，请在 **Emails / Additional Emails** 列中使用此格式：
|
||
|
||
```
|
||
["jane@twenty.com","jane.doe@twenty.com"]
|
||
```
|
||
|
||
### 域名字段
|
||
|
||
* **推荐格式**：`https://domain.com`
|
||
* 这与邮箱/日历同步所使用的格式一致（可防止重复）
|
||
* 填写这两列：
|
||
* **Domain / Domain Label**：`domain.com`
|
||
* **Domain / Domain URL**：`https://domain.com`
|
||
* 在您的文件内以及在 Twenty 中必须唯一
|
||
|
||
### 电话字段
|
||
|
||
电话是一个**嵌套字段**，需要多列：
|
||
|
||
| 列 | 示例 |
|
||
| --------------------------------------- | ------------ |
|
||
| **Phones / Primary Phone Number** | `4159095555` |
|
||
| **Phones / Primary Phone Country Code** | `US` |
|
||
| **电话 / 主电话号码国际区号** | `+1` |
|
||
|
||
### 地址字段
|
||
|
||
地址是一个**嵌套字段**，包含多个列（有些可以留空）：
|
||
|
||
* **Address / Address 1**：街道地址第 1 行
|
||
* **Address / Address 2**：街道地址第 2 行（可选）
|
||
* **Address / City**：城市名称
|
||
* **Address / State**：州或省
|
||
* **Address / Country**：国家名称
|
||
* **Address / Post Code**：邮政/ZIP 编码
|
||
|
||
### 日期字段
|
||
|
||
在整个文件中使用一致的格式：
|
||
|
||
* `YYYY-MM-DD`（推荐）：`2024-03-15`
|
||
* ISO 8601：`2024-03-15T10:30:00Z`
|
||
|
||
### 数字字段
|
||
|
||
* 仅数字（无文本）
|
||
* 小数使用点号：`1234.56`
|
||
* 不使用千位分隔符（不要写成 `1,234.56`）
|
||
|
||
### 货币字段
|
||
|
||
货币是一个**嵌套字段**，需要两列，且**两列都必须填写**：
|
||
|
||
| 列 | 示例 |
|
||
| --------------------- | --------- |
|
||
| **Amount / Amount** | `1234.56` |
|
||
| **Amount / Currency** | `USD` |
|
||
|
||
### 布尔字段
|
||
|
||
使用大写：`TRUE` 或 `FALSE`
|
||
|
||
<Warning>小写的 `true` 或 `false` 将无法使用。</Warning>
|
||
|
||
### 选择字段
|
||
|
||
使用选项的**API 名称**，而不是显示标签。
|
||
|
||
**如何查找 API 名称：**
|
||
|
||
1. 进入 **设置 → 数据模型**
|
||
2. 选择对象和字段
|
||
3. 启用**高级模式**（右下角切换）
|
||
4. 复制该 API 名称（例如：`OPTION_1`，而不是 "Option 1"）
|
||
|
||
<Note>新的选择项不会自动创建。 请在导入前于 **设置 → 数据模型** 中添加它们。</Note>
|
||
|
||
### 多选字段
|
||
|
||
以数组格式使用 API 名称：
|
||
|
||
```
|
||
["VALUE1","VALUE2"]
|
||
```
|
||
|
||
### 数组字段
|
||
|
||
使用 JSON 数组格式：
|
||
|
||
```
|
||
["value1","value2"]
|
||
```
|
||
|
||
### 评分字段
|
||
|
||
使用以下格式：`RATING_1`、`RATING_2`、`RATING_3`、`RATING_4` 或 `RATING_5`
|
||
|
||
### 链接/URL 字段
|
||
|
||
填写两列：
|
||
|
||
* **Links / Link Label**：`Twenty`
|
||
* **Links / Link URL**：`https://twenty.com`
|
||
|
||
对于次要链接，请使用 **Links / Secondary Links** 列：
|
||
|
||
```
|
||
[{"url":"https://twenty.com","label":"Twenty"}]
|
||
```
|
||
|
||
### JSON 字段
|
||
|
||
使用有效的 JSON 格式：
|
||
|
||
```
|
||
{"key":"value","key2":"value2"}
|
||
```
|
||
|
||
### ID 字段
|
||
|
||
* **可选**：如未提供，Twenty 将自动生成 ID
|
||
* **格式**：UUID（例如：`c776ee49-f608-4a77-8cc8-6fe96ae1e43f`）
|
||
* **使用场景**：包含 ID 以更新现有记录，而不是创建新记录
|
||
|
||
## 步骤 5：添加关系列（如果要关联记录）
|
||
|
||
要将记录关联到其他对象（例如，将人员关联到公司），请添加包含关联记录唯一标识符的列。
|
||
|
||
**示例**：将人员关联到公司
|
||
|
||
在您的人员 CSV 中添加一列：
|
||
|
||
```
|
||
firstName,lastName,email,companyDomain
|
||
John,Smith,john@acme.com,https://acme.com
|
||
Jane,Doe,jane@widgets.co,https://widgets.co
|
||
```
|
||
|
||
**关系的重要规则：**
|
||
|
||
* 父记录必须已存在于 Twenty 中
|
||
* 使用**域名 URL** 格式（`https://domain.com`），而不是标签
|
||
* 仅映射一个唯一标识符（不要同时包含 `companyId` 和 `companyDomain`）
|
||
* 对于工作区成员，请使用其**电子邮箱**（而不是姓名）
|
||
|
||
<Warning>
|
||
**导入顺序很重要！**
|
||
|
||
先导入“1”端，再导入“多”端：
|
||
1. **公司** 优先
|
||
2. **人员** 其次（包含公司引用）
|
||
3. **机会** 第三
|
||
|
||
在引用之前，父记录必须已存在。
|
||
</Warning>
|
||
|
||
详细说明请参见[如何导入关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)。
|
||
|
||
## 步骤 6：确保 Twenty 中存在这些字段
|
||
|
||
导入会创建**记录**，而非**字段**。 要导入的所有字段必须已在您的数据模型中存在。
|
||
|
||
**导入前：**
|
||
|
||
1. 进入 **设置 → 数据模型**
|
||
2. 选择您的对象
|
||
3. 创建所需的任何自定义字段
|
||
4. 记录准确的字段名称（必须与列标题匹配）
|
||
|
||
## 步骤 7：最终检查清单
|
||
|
||
在上传文件之前，请确认：
|
||
|
||
<Check>文件为 CSV、XLSX 或 XLS 格式</Check>
|
||
<Check>文件少于 10,000 条记录</Check>
|
||
<Check>编码为 UTF-8</Check>
|
||
<Check>没有重复的电子邮箱（针对人员）或域名（针对公司）</Check>
|
||
<Check>日期在全篇使用一致的格式</Check>
|
||
<Check>域名使用 `https://domain.com` 格式</Check>
|
||
<Check>布尔字段使用 `TRUE` 或 `FALSE`（大写）</Check>
|
||
<Check>选择字段使用 API 名称，而非显示标签</Check>
|
||
<Check>所有自定义字段已存在于 设置 → 数据模型 中</Check>
|
||
<Check>父记录先于子记录导入</Check>
|
||
<Check>关系列引用现有记录</Check>
|
||
|
||
## 常见错误及避免方法
|
||
|
||
| 错误 | 解决方案 |
|
||
| ------------------- | ---------------------------- |
|
||
| 使用 `true` 而非 `TRUE` | 布尔值必须为大写 |
|
||
| 在选择字段中使用显示标签 | 在“设置”中查找并使用 API 名称 |
|
||
| 在公司之前导入人员 | 始终先导入父对象 |
|
||
| 货币字段缺少货币代码 | 填写金额和货币两列 |
|
||
| 域名格式错误 | 始终使用 `https://domain.com` 格式 |
|
||
| 为关系映射了多个唯一字段 | 仅映射一个（域名或 ID，不要同时映射） |
|
||
|
||
## 下一步
|
||
|
||
您的文件已准备就绪！ 现在：
|
||
|
||
* [导入公司](/l/zh/user-guide/data-migration/how-tos/import-companies-via-csv)（先导入这些）
|
||
* [导入联系人](/l/zh/user-guide/data-migration/how-tos/import-contacts-via-csv)
|
||
* [修复任何导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)
|