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