148 lines
4.5 KiB
Plaintext
148 lines
4.5 KiB
Plaintext
---
|
||
title: 接口
|
||
description: 使用 REST 或 GraphQL 以编程方式查询和修改您的客户关系管理数据。
|
||
---
|
||
|
||
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
||
|
||
Twenty 的设计对开发者友好，提供适配您自定义数据模型的强大 API。 我们提供四种不同的 API 类型来满足不同的集成需求。
|
||
|
||
## 开发者优先的方法
|
||
|
||
Twenty 会针对您的数据模型生成专用 API：
|
||
|
||
* **无需长 ID**：直接在端点中使用对象和字段名称
|
||
* **标准与自定义对象平等对待**：您的自定义对象将享有与内置对象相同的 API 支持
|
||
* **专用端点**：每个对象和字段都有自己的 API 端点
|
||
* **自定义文档**：专门为您的工作区的数据模型生成
|
||
|
||
<Note>
|
||
创建 API 密钥后，可在 **设置 → API & Webhooks** 中查看您的个性化 API 文档。 由于 Twenty 会生成与您的自定义数据模型相匹配的 API，因此文档对您的工作区是唯一的。
|
||
</Note>
|
||
|
||
## 两种 API 类型
|
||
|
||
### 核心 API
|
||
|
||
访问路径：`/rest/`或`/graphql/`。
|
||
|
||
处理您实际的**记录**（数据）：
|
||
|
||
* 创建、读取、更新、删除 People、Companies、Opportunities 等。
|
||
* 查询并筛选数据
|
||
* 管理记录关系
|
||
|
||
### 元数据 API
|
||
|
||
访问路径：`/rest/metadata/`或`/metadata/`。
|
||
|
||
管理您的**工作区和数据模型**：
|
||
|
||
* 创建、修改或删除对象和字段
|
||
* 配置工作区设置
|
||
* 定义对象之间的关系
|
||
|
||
## REST 与 GraphQL
|
||
|
||
核心 API 和元数据 API 均提供 REST 和 GraphQL 格式：
|
||
|
||
| 格式 | 可用操作 |
|
||
| ----------- | ------------------------------- |
|
||
| **REST** | CRUD、批量操作、Upsert |
|
||
| **GraphQL** | 同上 + **批量 Upsert**，在一次调用中进行关系查询 |
|
||
|
||
可根据需要选择 — 两种格式访问的是同一份数据。
|
||
|
||
## API 端点
|
||
|
||
| 环境 | 基础 URL |
|
||
| ------- | ------------------------- |
|
||
| **云端** | `https://api.twenty.com/` |
|
||
| **自托管** | `https://{your-domain}/` |
|
||
|
||
## 身份验证
|
||
|
||
每个 API 请求都需要在请求头中包含 API 密钥：
|
||
|
||
```
|
||
Authorization: Bearer YOUR_API_KEY
|
||
```
|
||
|
||
### 创建 API 密钥
|
||
|
||
1. 前往 **设置 → APIs & Webhooks**
|
||
2. 点击 **+ 创建密钥**
|
||
3. 配置：
|
||
* **名称**：密钥的描述性名称
|
||
* **到期日期**：密钥的到期时间
|
||
4. 单击 **保存**
|
||
5. **立即复制** — 密钥仅显示一次
|
||
|
||
<VimeoEmbed videoId="928786722" title="创建 API 密钥" />
|
||
|
||
<Warning>
|
||
您的 API 密钥可访问敏感数据。 不要与不受信任的服务共享它。 如果遭到泄露，请立即将其禁用并生成一个新的。
|
||
</Warning>
|
||
|
||
### 为 API 密钥分配角色
|
||
|
||
为提高安全性，请分配特定角色以限制访问：
|
||
|
||
1. 进入 **设置 → 角色**
|
||
2. 点击要分配的角色
|
||
3. 打开 **分配** 选项卡
|
||
4. 在 **API Keys** 下，点击 **+ Assign to API key**
|
||
5. 选择该 API 密钥
|
||
|
||
该密钥将继承该角色的权限。 详见 [权限](/l/zh/user-guide/permissions-access/capabilities/permissions)。
|
||
|
||
### 管理 API 密钥
|
||
|
||
**Regenerate**: 设置 → APIs & Webhooks → 点击密钥 → **Regenerate**
|
||
|
||
**Delete**: 设置 → APIs & Webhooks → 点击密钥 → **Delete**
|
||
|
||
## API 操作台
|
||
|
||
使用我们内置的操作台，可直接在浏览器中测试您的 API — 同时支持 **REST** 和 **GraphQL**。
|
||
|
||
### 访问操作台
|
||
|
||
1. 前往 **设置 → APIs & Webhooks**
|
||
2. 创建 API 密钥（必需）
|
||
3. 点击 **REST API** 或 **GraphQL API** 打开操作台
|
||
|
||
### 您将获得
|
||
|
||
* **交互式文档**：针对您的特定数据模型生成
|
||
* **实时测试**：对您的工作区执行真实的 API 调用
|
||
* **架构浏览器**：浏览可用的对象、字段和关系
|
||
* **请求构建器**：使用自动补全构建查询
|
||
|
||
操作台会反映您的自定义对象和字段，因此文档始终与您的工作区保持一致且准确。
|
||
|
||
## 批量操作
|
||
|
||
REST 和 GraphQL 均支持批量操作：
|
||
|
||
* **批量大小**：每个请求最多 60 条记录
|
||
* **操作**：创建、更新、删除多条记录
|
||
|
||
**仅 GraphQL 功能：**
|
||
|
||
* **批量 Upsert**：在一次调用中创建或更新
|
||
* 使用复数对象名称（例如，用 `CreateCompanies` 而不是 `CreateCompany`）
|
||
|
||
## 速率限制
|
||
|
||
为确保平台稳定性，API 请求将受到限流：
|
||
|
||
| 限制 | 值 |
|
||
| -------- | ----------- |
|
||
| **请求** | 每分钟 100 次调用 |
|
||
| **批量大小** | 每次调用 60 条记录 |
|
||
|
||
<Tip>
|
||
使用批量操作以最大化吞吐量 — 在一次 API 调用中处理最多 60 条记录，而不是发起单独的请求。
|
||
</Tip>
|