概览
Twenty 提供 GraphQL 和 REST API，用于以编程方式导入数据。 当 CSV 导入不适合您的数据量，或您需要自动化、定期的导入时，请使用 API。何时使用 API 导入
| 场景 | 推荐方法 |
|---|---|
| 少于 10,000 条记录 | CSV 导入 |
| 10,000 - 50,000 条记录 | CSV 导入（拆分为多个文件） |
| 50,000+ 条记录 | API 导入 |
| 一次性迁移 | 两者皆可（取决于数据量） |
| 定期导入 | API 导入 |
| 实时同步 | API 导入 |
| 与其他系统集成 | API 导入 |
对于包含数十万条记录的数据集，API 比多次 CSV 导入显著更快且更可靠。
API 速率限制
Twenty 实施速率限制以确保系统稳定性：| 限制 | 值 |
|---|---|
| 每分钟请求数 | 100 |
| 每次批量调用的记录数 | 60 |
| 最大吞吐量 | ~6,000 条记录/分钟 |
开始使用
步骤 1：获取您的 API 密钥
- 前往 设置 → 开发者
- 点击 + 创建 API 密钥
- 为您的密钥指定一个描述性名称
- 立即复制该 API 密钥（不会再次显示）
- 将其安全存储
步骤 2：选择您的 API
Twenty 支持两种 API 类型： 两种 API 都支持：- 创建、读取、更新和删除记录
- 批量操作 — 每次调用最多创建或更新 60 条记录
步骤 3：规划您的导入顺序
与 CSV 导入一样，对于关联关系，顺序很重要：- 公司 优先（无依赖）
- 人员 其次（可关联到公司）
- 商机 第三（可关联到公司和人员）
- 任务/笔记（可关联到以上任一项）
- 自定义对象（按照其依赖关系）
最佳实践
批量处理请求
- 不要逐条发送记录
- 每次 API 调用最多分组处理 60 条记录
- 这可在速率限制内最大化吞吐量
处理速率限制
- 在请求之间实施延迟（持续导入时至少 600ms）
- 达到限制时使用指数退避
- 监控 429（请求过多）响应
先验证数据
- 在导入前清洗并验证数据
- 检查必填字段是否已填写
- 验证格式是否符合 Twenty 的要求 (参见 字段映射)
记录一切
- 记录每一条导入的记录（包括 ID）
- 记录错误及其完整上下文
- 这有助于调试问题并验证完成情况
先进行测试
- 使用小批量进行测试（10-20 条记录）
- 验证数据在 Twenty 中显示是否正确
- 然后执行完整导入
使用合并插入避免重复
GraphQL API 支持批量合并插入 — 若记录已存在则更新，不存在则创建。 这可以在重新运行导入时防止重复。查找对象和字段名称
查看可用的对象和字段：- 前往 设置 → API 和 Webhooks
- 浏览 Metadata API
- 查看所有标准和自定义对象及其字段
专业服务
对于复杂的 API 迁移，我们的合作伙伴可以提供帮助：| 服务 | 包含内容 |
|---|---|
| 数据模型设计 | 设计最优的数据结构 |
| 迁移脚本 | 编写并运行导入脚本 |
| 数据转换 | 处理复杂的映射与清理 |
| 验证与 QA | 验证迁移是否完成 |
- 迁移 100,000+ 条记录
- 复杂的数据转换
- 紧迫的时间安排
- 缺乏开发人员资源的团队
常见问题
GraphQL 与 REST 有何区别？
GraphQL 与 REST 有何区别？
GraphQL 允许您在一次查询中准确请求所需数据，并且更适合复杂操作。 REST 使用标准的 HTTP 方法（GET、POST、PUT、DELETE），如果您使用过传统 API，可能会更熟悉。
我可以通过 API 更新现有记录吗？
我可以通过 API 更新现有记录吗？
是! 使用 update mutation（GraphQL）或带有记录
id 的 PUT/PATCH 请求（REST）。如何处理重复数据？
如何处理重复数据？
首先使用唯一标识符（email、domain）查询现有记录。 存在则更新，不存在则创建。
我可以通过 API 删除记录吗？
我可以通过 API 删除记录吗？
可以，使用 delete mutation（GraphQL）或 DELETE 请求（REST）。
是否提供 Python 或 Node.js 的 SDK？
是否提供 Python 或 Node.js 的 SDK？
目前没有，但这两种 API 可与任何语言中的任意 HTTP 客户端配合使用。