Обзор
Twenty предоставляет как GraphQL, так и REST API для программного импорта данных. Используйте API, когда импорт CSV непрактичен для вашего объёма данных или когда вам нужен автоматизированный регулярный импорт.Когда использовать импорт через API
Для наборов данных в сотни тысяч записей API значительно быстрее и надёжнее, чем многократный импорт CSV.
Лимиты скорости API
Twenty применяет лимиты скорости для обеспечения стабильности системы:Начало работы
Шаг 1: Получите свой API-ключ
- Перейдите в Настройки → Разработчики
- Нажмите + Создать API-ключ
- Дайте вашему ключу информативное имя
- Сразу скопируйте API-ключ (он больше не будет показан)
- Храните его в защищённом месте
Шаг 2: Выберите API
Twenty поддерживает два типа API:
Оба 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-клиентом на любом языке.