github-actions[bot]
982f0c4a4d
Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
177 lines
12 KiB
Plaintext
177 lines
12 KiB
Plaintext
---
|
||
title: Импорт данных через API
|
||
description: Когда и как использовать API Twenty для массового импорта данных.
|
||
---
|
||
|
||
## Обзор
|
||
|
||
Twenty предоставляет как **GraphQL**, так и **REST API** для программного импорта данных. Используйте API, когда импорт CSV непрактичен для вашего объёма данных или когда вам нужен автоматизированный регулярный импорт.
|
||
|
||
## Когда использовать импорт через 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:
|
||
|
||
| API | Лучше всего подходит для | Документация |
|
||
| ----------- | ------------------------------------------------------------ | --------------------------------------------- |
|
||
| **GraphQL** | Гибкие запросы, получение связанных данных, сложные операции | [Документация по API](/l/ru/developers/extend/api) |
|
||
| **REST** | Простые операции CRUD, привычные шаблоны REST | [Документация по API](/l/ru/developers/extend/api) |
|
||
|
||
Оба API поддерживают:
|
||
|
||
* Создание, чтение, обновление и удаление записей
|
||
* **Пакетные операции** — создание или обновление до 60 записей за один вызов
|
||
|
||
**Для импорта используйте пакетные операции**, чтобы максимизировать пропускную способность в рамках лимитов.
|
||
|
||
### Шаг 3: Спланируйте порядок импорта
|
||
|
||
Как и при импорте CSV, для связей **важен порядок**:
|
||
|
||
1. **Компании** в первую очередь (без зависимостей)
|
||
2. **Контакты** во вторую очередь (могут быть связаны с компаниями)
|
||
3. **Возможности** в третью очередь (могут быть связаны с компаниями и контактами)
|
||
4. **Задачи/Заметки** (могут быть связаны с любым из вышеперечисленных)
|
||
5. **Пользовательские объекты** (с учётом их зависимостей)
|
||
|
||
## Лучшие практики
|
||
|
||
### Объединяйте запросы в пакеты
|
||
|
||
* Не отправляйте записи по одной
|
||
* Группируйте до **60 записей на один вызов API**
|
||
* Так вы максимально используете пропускную способность в рамках лимитов
|
||
|
||
### Обрабатывайте ограничения скорости
|
||
|
||
* Реализуйте задержки между запросами (минимум 600 мс для длительных импортов)
|
||
* При достижении лимитов используйте экспоненциальное увеличение интервала повторных попыток
|
||
* Отслеживайте ответы 429 (Too Many Requests)
|
||
|
||
### Сначала проверьте данные
|
||
|
||
* Очистите и проверьте данные перед импортом
|
||
* Проверьте, что обязательные поля заполнены
|
||
* Убедитесь, что форматы соответствуют требованиям Twenty (см. [Сопоставление полей](/l/ru/user-guide/data-migration/capabilities/field-mapping))
|
||
|
||
### Логируйте всё
|
||
|
||
* Логируйте каждую импортированную запись (включая идентификаторы)
|
||
* Логируйте ошибки с полным контекстом
|
||
* Это помогает устранять неполадки и подтверждать завершение
|
||
|
||
### Сначала протестируйте
|
||
|
||
* Протестируйте на небольшой выборке (10-20 записей)
|
||
* Проверьте, что данные корректно отображаются в Twenty
|
||
* Затем запустите полный импорт
|
||
|
||
### Upsert для предотвращения дубликатов
|
||
|
||
GraphQL API поддерживает **пакетный upsert** — обновление, если запись существует, и создание, если нет. Это предотвращает дубликаты при повторном запуске импорта.
|
||
|
||
## Поиск названий объектов и полей
|
||
|
||
Чтобы увидеть доступные объекты и поля:
|
||
|
||
1. Перейдите в **Настройки → API и вебхуки**
|
||
2. Просмотрите **Metadata API**
|
||
3. Просмотрите все стандартные и пользовательские объекты и их поля
|
||
|
||
В документации перечислены все стандартные и пользовательские объекты, их поля и ожидаемые типы данных.
|
||
|
||
## Профессиональные услуги
|
||
|
||
Для сложных миграций по API наши партнёры могут помочь:
|
||
|
||
| Услуга | Что включено |
|
||
| -------------------------------- | ------------------------------------------------- |
|
||
| **Проектирование модели данных** | проектирование оптимальной структуры данных |
|
||
| **Скрипты миграции** | написание и запуск скриптов импорта |
|
||
| **Преобразование данных** | обработка сложного сопоставления и очистки данных |
|
||
| **Проверка и контроль качества** | проверка завершённости миграции |
|
||
|
||
**Лучше всего подходит для:**
|
||
|
||
* Миграции объёмом 100 000+ записей
|
||
* Сложные преобразования данных
|
||
* Сжатые сроки
|
||
* Команды без ресурсов на разработку
|
||
|
||
Свяжитесь с нами по адресу [contact@twenty.com](mailto:contact@twenty.com) или изучите наши [услуги по внедрению](/l/ru/user-guide/getting-started/capabilities/implementation-services).
|
||
|
||
## Часто задаваемые вопросы
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="В чём разница между GraphQL и REST?">
|
||
GraphQL позволяет запрашивать ровно те данные, которые нужны, в одном запросе и лучше подходит для сложных операций. REST использует стандартные методы HTTP (GET, POST, PUT, DELETE) и может быть более привычен, если вы работали с традиционными API.
|
||
</Accordion>
|
||
|
||
<Accordion title="Могу ли я обновлять существующие записи через API?">
|
||
Да! Используйте мутации обновления (GraphQL) или запросы PUT/PATCH (REST) с `id` записи.
|
||
</Accordion>
|
||
|
||
<Accordion title="Как обрабатывать дубликаты?">
|
||
Сначала запросите существующие записи, используя уникальные идентификаторы (email, домен). Обновляйте, если запись существует, и создавайте, если нет.
|
||
</Accordion>
|
||
|
||
<Accordion title="Могу ли я удалять записи через API?">
|
||
Да, используйте мутации удаления (GraphQL) или запросы DELETE (REST).
|
||
</Accordion>
|
||
|
||
<Accordion title="Есть ли SDK для Python или Node.js?">
|
||
Пока нет, но оба API работают с любым HTTP-клиентом на любом языке.
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## Документация по API
|
||
|
||
Полная информация о реализации, примеры кода и справочник по схеме:
|
||
|
||
* [Документация по API](/l/ru/developers/extend/api)
|