Обзор
Twenty предоставляет как GraphQL, так и REST API для программного импорта данных. Используйте API, когда импорт CSV непрактичен для вашего объёма данных или когда вам нужен автоматизированный регулярный импорт.Когда использовать импорт через 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 | Лучше всего подходит для | Документация |
|---|---|---|
| GraphQL | Гибкие запросы, получение связанных данных, сложные операции | Документация по API |
| REST | Простые операции CRUD, привычные шаблоны REST | Документация по API |
- Создание, чтение, обновление и удаление записей
- Пакетные операции — создание или обновление до 60 записей за один вызов
Шаг 3: Спланируйте порядок импорта
Как и при импорте CSV, для связей важен порядок:- Компании в первую очередь (без зависимостей)
- Контакты во вторую очередь (могут быть связаны с компаниями)
- Возможности в третью очередь (могут быть связаны с компаниями и контактами)
- Задачи/Заметки (могут быть связаны с любым из вышеперечисленных)
- Пользовательские объекты (с учётом их зависимостей)
Лучшие практики
Объединяйте запросы в пакеты
- Не отправляйте записи по одной
- Группируйте до 60 записей на один вызов API
- Так вы максимально используете пропускную способность в рамках лимитов
Обрабатывайте ограничения скорости
- Реализуйте задержки между запросами (минимум 600 мс для длительных импортов)
- При достижении лимитов используйте экспоненциальное увеличение интервала повторных попыток
- Отслеживайте ответы 429 (Too Many Requests)
Сначала проверьте данные
- Очистите и проверьте данные перед импортом
- Проверьте, что обязательные поля заполнены
- Убедитесь, что форматы соответствуют требованиям Twenty (см. Сопоставление полей)
Логируйте всё
- Логируйте каждую импортированную запись (включая идентификаторы)
- Логируйте ошибки с полным контекстом
- Это помогает устранять неполадки и подтверждать завершение
Сначала протестируйте
- Протестируйте на небольшой выборке (10-20 записей)
- Проверьте, что данные корректно отображаются в Twenty
- Затем запустите полный импорт
Upsert для предотвращения дубликатов
GraphQL API поддерживает пакетный upsert — обновление, если запись существует, и создание, если нет. Это предотвращает дубликаты при повторном запуске импорта.Поиск названий объектов и полей
Чтобы увидеть доступные объекты и поля:- Перейдите в Настройки → API и вебхуки
- Просмотрите Metadata API
- Просмотрите все стандартные и пользовательские объекты и их поля
Профессиональные услуги
Для сложных миграций по API наши партнёры могут помочь:| Услуга | Что включено |
|---|---|
| Проектирование модели данных | проектирование оптимальной структуры данных |
| Скрипты миграции | написание и запуск скриптов импорта |
| Преобразование данных | обработка сложного сопоставления и очистки данных |
| Проверка и контроль качества | проверка завершённости миграции |
- Миграции объёмом 100 000+ записей
- Сложные преобразования данных
- Сжатые сроки
- Команды без ресурсов на разработку
Часто задаваемые вопросы
В чём разница между GraphQL и REST?
В чём разница между GraphQL и REST?
GraphQL позволяет запрашивать ровно те данные, которые нужны, в одном запросе и лучше подходит для сложных операций. REST использует стандартные методы HTTP (GET, POST, PUT, DELETE) и может быть более привычен, если вы работали с традиционными API.
Могу ли я обновлять существующие записи через API?
Могу ли я обновлять существующие записи через API?
Да! Используйте мутации обновления (GraphQL) или запросы PUT/PATCH (REST) с
id записи.Как обрабатывать дубликаты?
Как обрабатывать дубликаты?
Сначала запросите существующие записи, используя уникальные идентификаторы (email, домен). Обновляйте, если запись существует, и создавайте, если нет.
Могу ли я удалять записи через API?
Могу ли я удалять записи через API?
Да, используйте мутации удаления (GraphQL) или запросы DELETE (REST).
Есть ли SDK для Python или Node.js?
Есть ли SDK для Python или Node.js?
Пока нет, но оба API работают с любым HTTP-клиентом на любом языке.