982f0c4a4d
Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
148 lines
8.7 KiB
Plaintext
148 lines
8.7 KiB
Plaintext
---
|
|
title: API
|
|
description: Запрашивайте и изменяйте данные CRM программно с помощью REST или GraphQL.
|
|
---
|
|
|
|
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
|
|
|
Twenty разработан для удобства разработчиков и предлагает мощные API, которые адаптируются к вашей пользовательской модели данных. Мы предоставляем четыре различных типа API, чтобы удовлетворить различные интеграционные потребности.
|
|
|
|
## Подход, ориентированный на разработчиков
|
|
|
|
Twenty генерирует API специально для вашей модели данных:
|
|
|
|
* **Длинные ID не требуются**: используйте названия объектов и полей прямо в конечных точках.
|
|
* **Стандартные и пользовательские объекты обрабатываются одинаково**: ваши пользовательские объекты получают такой же доступ к API, как и встроенные.
|
|
* **Выделенные конечные точки**: каждый объект и поле получают свою собственную конечную точку API.
|
|
* **Пользовательская документация**: генерируется специально для модели данных вашего рабочего пространства.
|
|
|
|
<Note>
|
|
Персонализированная документация по вашему API доступна в разделе **Настройки → API и вебхуки** после создания ключа API. Поскольку Twenty генерирует API, соответствующие вашей пользовательской модели данных, документация уникальна для вашего рабочего пространства.
|
|
</Note>
|
|
|
|
## Два типа API
|
|
|
|
### Основной API
|
|
|
|
Доступен на `/rest/` или `/graphql/`
|
|
|
|
Работайте с реальными **записями** (данными):
|
|
|
|
* Создавайте, читайте, обновляйте и удаляйте People, Companies, Opportunities и т. д.
|
|
* Запрашивайте и фильтруйте данные
|
|
* Управление отношениями записей.
|
|
|
|
### API метаданных
|
|
|
|
Доступен на `/rest/metadata/` или `/metadata/`
|
|
|
|
Управляйте своим **рабочим пространством и моделью данных**:
|
|
|
|
* Создание, изменение или удаление объектов и полей.
|
|
* Настройка параметров рабочего пространства.
|
|
* Определяйте связи между объектами
|
|
|
|
## REST против GraphQL
|
|
|
|
И Core, и Metadata 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. Перейдите в **Настройки → API и вебхуки**
|
|
2. Нажмите **+ Создать ключ**
|
|
3. Настройки:
|
|
* **Имя**: описательное название для ключа
|
|
* **Дата истечения**: когда истекает срок действия ключа
|
|
4. Нажмите **Сохранить**
|
|
5. **Скопируйте сразу** — ключ показывается только один раз
|
|
|
|
<VimeoEmbed videoId="928786722" title="Создание ключа API" />
|
|
|
|
<Warning>
|
|
Ваш ключ API предоставляет доступ к конфиденциальным данным. Не делитесь им с ненадежными сервисами. Если он скомпрометирован, немедленно отключите его и создайте новый.
|
|
</Warning>
|
|
|
|
### Назначить роль ключу API
|
|
|
|
Для повышения безопасности назначьте конкретную роль, чтобы ограничить доступ:
|
|
|
|
1. Перейдите в **Настройки → Роли**
|
|
2. Нажмите на роль, которую хотите назначить
|
|
3. Откройте вкладку **Назначение**
|
|
4. В разделе **Ключи API** нажмите **+ Назначить ключу API**
|
|
5. Выберите ключ API
|
|
|
|
Ключ унаследует разрешения этой роли. См. [Разрешения](/l/ru/user-guide/permissions-access/capabilities/permissions) для подробностей.
|
|
|
|
### Управление API-ключами
|
|
|
|
**Сгенерировать заново**: Настройки → API и вебхуки → Нажмите на ключ → **Сгенерировать заново**
|
|
|
|
**Удалить**: Настройки → API и вебхуки → Нажмите ключ → **Удалить**
|
|
|
|
## Песочница API
|
|
|
|
Тестируйте свои API прямо в браузере с нашей встроенной песочницей — доступной как для **REST**, так и для **GraphQL**.
|
|
|
|
### Доступ к песочнице
|
|
|
|
1. Перейдите в **Настройки → API и вебхуки**
|
|
2. Создайте ключ API (обязательно)
|
|
3. Нажмите на **REST API** или **GraphQL API**, чтобы открыть песочницу
|
|
|
|
### Что вы получаете
|
|
|
|
* **Интерактивная документация**: генерируется для вашей конкретной модели данных
|
|
* **Тестирование в реальном времени**: выполняйте реальные вызовы API к вашему рабочему пространству
|
|
* **Обозреватель схемы**: просматривайте доступные объекты, поля и связи
|
|
* **Конструктор запросов**: создавайте запросы с автодополнением
|
|
|
|
Песочница отражает ваши пользовательские объекты и поля, поэтому документация всегда точна для вашего рабочего пространства.
|
|
|
|
## Пакетные операции
|
|
|
|
И REST, и GraphQL поддерживают пакетные операции:
|
|
|
|
* **Размер пакета**: до 60 записей на запрос.
|
|
* **Операции**: создание, обновление, удаление нескольких записей
|
|
|
|
**Функции только для GraphQL:**
|
|
|
|
* **Пакетный upsert**: создание или обновление за один вызов
|
|
* Используйте имена объектов во множественном числе (например, `CreateCompanies` вместо `CreateCompany`)
|
|
|
|
## Лимиты скорости
|
|
|
|
Запросы к API ограничиваются для обеспечения стабильности платформы:
|
|
|
|
| Лимит | Значение |
|
|
| ----------------- | ------------------------- |
|
|
| **Запросы** | 100 запросов в минуту |
|
|
| **Размер пакета** | 60 записей за один запрос |
|
|
|
|
<Tip>
|
|
Используйте пакетные операции, чтобы максимизировать пропускную способность — обрабатывайте до 60 записей за один запрос API вместо выполнения отдельных запросов.
|
|
</Tip>
|