github-actions[bot]
6bc64f78fc
Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com>
702 lines
36 KiB
Plaintext
702 lines
36 KiB
Plaintext
---
|
||
title: Приложения Twenty
|
||
description: Создавайте и управляйте настройками Twenty в виде кода.
|
||
---
|
||
|
||
<Warning>
|
||
Приложения сейчас проходят альфа-тестирование. Функциональность работает, но продолжает развиваться.
|
||
</Warning>
|
||
|
||
## Что такое приложения?
|
||
|
||
Приложения позволяют создавать и управлять настройками Twenty **в виде кода**. Вместо настройки всего через интерфейс вы определяете модель данных и бессерверные функции в коде — так быстрее создавать, поддерживать и развёртывать в нескольких рабочих пространствах.
|
||
|
||
**Что вы можете делать уже сегодня:**
|
||
|
||
* Определяйте пользовательские объекты и поля в виде кода (управляемая модель данных)
|
||
* Создавайте бессерверные функции с пользовательскими триггерами
|
||
* Развёртывайте одно и то же приложение в нескольких рабочих пространствах
|
||
|
||
**Скоро:**
|
||
|
||
* Пользовательские макеты и компоненты интерфейса
|
||
|
||
## Требования
|
||
|
||
* Node.js 24+ и Yarn 4
|
||
* Рабочее пространство Twenty и ключ API (создайте его на https://app.twenty.com/settings/api-webhooks)
|
||
|
||
## Начало работы
|
||
|
||
Создайте новое приложение с помощью официального генератора, затем выполните аутентификацию и начните разработку:
|
||
|
||
```bash filename="Terminal"
|
||
# Scaffold a new app
|
||
npx create-twenty-app@latest my-twenty-app
|
||
cd my-twenty-app
|
||
|
||
# Authenticate using your API key (you'll be prompted)
|
||
yarn auth:login
|
||
|
||
# Start dev mode: automatically syncs local changes to your workspace
|
||
yarn app:dev
|
||
```
|
||
|
||
Отсюда вы можете:
|
||
|
||
```bash filename="Terminal"
|
||
# Add a new entity to your application (guided)
|
||
yarn app:create-entity
|
||
|
||
# Generate a typed Twenty client and workspace entity types
|
||
yarn app:generate
|
||
|
||
# Run a one‑time sync (instead of watch mode)
|
||
yarn app:sync
|
||
|
||
# Watch your application's functions logs
|
||
yarn function:logs
|
||
|
||
# Execute a function by name
|
||
yarn function:execute -n my-function -p '{"name": "test"}'
|
||
|
||
# Uninstall the application from the current workspace
|
||
yarn app:uninstall
|
||
|
||
# Display commands' help
|
||
yarn app:help
|
||
```
|
||
|
||
Смотрите также: страницы справки CLI для [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) и [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
|
||
|
||
## Структура проекта (сгенерированного)
|
||
|
||
Когда вы запускаете `npx create-twenty-app@latest my-twenty-app`, генератор:
|
||
|
||
* Копирует минимальное базовое приложение в `my-twenty-app/`
|
||
* Добавляет локальную зависимость `twenty-sdk` и конфигурацию Yarn 4
|
||
* Создаёт файлы конфигурации и скрипты, подключённые к CLI `twenty`
|
||
* Генерирует конфигурацию приложения по умолчанию и роль функции по умолчанию
|
||
|
||
Свежесгенерированное приложение выглядит так:
|
||
|
||
```text filename="my-twenty-app/"
|
||
my-twenty-app/
|
||
package.json
|
||
yarn.lock
|
||
.gitignore
|
||
.nvmrc
|
||
.yarnrc.yml
|
||
.yarn/
|
||
releases/
|
||
yarn-4.9.2.cjs
|
||
install-state.gz
|
||
eslint.config.mjs
|
||
tsconfig.json
|
||
README.md
|
||
src/
|
||
app/
|
||
application.config.ts # Required - main application configuration
|
||
default-function.role.ts # Default role for serverless functions
|
||
// your entities (*.object.ts, *.function.ts, *.role.ts)
|
||
utils/ # Optional - handler implementations & utilities
|
||
```
|
||
|
||
### Соглашения важнее конфигурации
|
||
|
||
Приложения используют подход **соглашения важнее конфигурации**, при котором сущности определяются по суффиксу файла. Это позволяет гибко организовать структуру в папке `src/app/`:
|
||
|
||
| Суффикс файла | Тип сущности |
|
||
| --------------- | ------------------------------------- |
|
||
| `*.object.ts` | Определения пользовательских объектов |
|
||
| `*.function.ts` | Определения бессерверных функций |
|
||
| `*.role.ts` | Определения ролей |
|
||
|
||
### Поддерживаемые способы организации папок
|
||
|
||
Вы можете организовать свои сущности по любому из этих шаблонов:
|
||
|
||
**Традиционный (по типам):**
|
||
|
||
```text
|
||
src/app/
|
||
├── application.config.ts
|
||
├── objects/
|
||
│ └── postCard.object.ts
|
||
├── functions/
|
||
│ └── createPostCard.function.ts
|
||
└── roles/
|
||
└── admin.role.ts
|
||
```
|
||
|
||
**По функциональности:**
|
||
|
||
```text
|
||
src/app/
|
||
├── application.config.ts
|
||
└── post-card/
|
||
├── postCard.object.ts
|
||
├── createPostCard.function.ts
|
||
└── postCardAdmin.role.ts
|
||
```
|
||
|
||
**Плоский:**
|
||
|
||
```text
|
||
src/app/
|
||
├── application.config.ts
|
||
├── postCard.object.ts
|
||
├── createPostCard.function.ts
|
||
└── admin.role.ts
|
||
```
|
||
|
||
В общих чертах:
|
||
|
||
* **package.json**: Объявляет имя приложения, версию, движки (Node 24+, Yarn 4) и добавляет `twenty-sdk`, а также скрипты вроде `dev`, `sync`, `generate`, `create-entity`, `logs`, `uninstall` и `auth`, которые делегируют выполнение локальному CLI `twenty`.
|
||
* **.gitignore**: Игнорирует распространённые артефакты, такие как `node_modules`, `.yarn`, `generated/` (типизированный клиент), `dist/`, `build/`, каталоги coverage, файлы журналов и файлы `.env*`.
|
||
* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Фиксируют и настраивают используемый в проекте инструментарий Yarn 4.
|
||
* **.nvmrc**: Фиксирует версию Node.js, ожидаемую проектом.
|
||
* **eslint.config.mjs** и **tsconfig.json**: Обеспечивают линтинг и конфигурацию TypeScript для исходников вашего приложения на TypeScript.
|
||
* **README.md**: Короткий README в корне приложения с базовыми инструкциями.
|
||
* **src/app/**: Основное место, где вы определяете приложение как код:
|
||
* `application.config.ts`: Глобальная конфигурация вашего приложения (метаданные и параметры выполнения). См. раздел «Конфигурация приложения» ниже.
|
||
* `*.role.ts`: Определения ролей, используемых вашими бессерверными функциями. См. раздел «Роль функции по умолчанию» ниже.
|
||
* `*.object.ts`: Определения пользовательских объектов.
|
||
* `*.function.ts`: Определения бессерверных функций.
|
||
* **src/utils/**: Необязательная папка для реализаций обработчиков и утилит.
|
||
|
||
Позднее команды добавят больше файлов и папок:
|
||
|
||
* `yarn app:generate` создаст папку `generated/` (типизированный клиент Twenty + типы рабочего пространства).
|
||
* `yarn app:create-entity` добавит файлы определений сущностей в `src/app/` для ваших пользовательских объектов, функций или ролей.
|
||
l
|
||
|
||
## Аутентификация
|
||
|
||
При первом запуске `yarn auth:login` вам будет предложено указать:
|
||
|
||
* URL API (по умолчанию http://localhost:3000 или текущий профиль рабочего пространства)
|
||
* Ключ API
|
||
|
||
Ваши учётные данные хранятся для каждого пользователя в `~/.twenty/config.json`. You can maintain multiple profiles and switch between them.
|
||
|
||
### Managing workspaces
|
||
|
||
```bash filename="Terminal"
|
||
# Login interactively (recommended)
|
||
yarn auth:login
|
||
|
||
# Login to a specific workspace profile
|
||
yarn auth:login --workspace my-custom-workspace
|
||
|
||
# List all configured workspaces
|
||
yarn auth:list
|
||
|
||
# Switch the default workspace (interactive)
|
||
yarn auth:switch
|
||
|
||
# Switch to a specific workspace
|
||
yarn auth:switch production
|
||
|
||
# Check current authentication status
|
||
yarn auth:status
|
||
```
|
||
|
||
Once you've switched workspaces with `auth:switch`, all subsequent commands will use that workspace by default. You can still override it temporarily with `--workspace <name>`.
|
||
|
||
## Используйте ресурсы SDK (типы и конфигурация)
|
||
|
||
Пакет twenty-sdk предоставляет типизированные строительные блоки и вспомогательные функции, которые вы используете внутри своего приложения. Ниже — ключевые части, с которыми вы будете работать чаще всего.
|
||
|
||
### Вспомогательные функции
|
||
|
||
SDK предоставляет четыре вспомогательных функции с встроенной валидацией для определения сущностей вашего приложения:
|
||
|
||
| Функция | Назначение |
|
||
| ------------------ | ----------------------------------------------- |
|
||
| `defineApp()` | Настраивает метаданные приложения |
|
||
| `defineObject()` | Определяет пользовательские объекты с полями |
|
||
| `defineFunction()` | Определяет бессерверные функции с обработчиками |
|
||
| `defineRole()` | Настраивает права роли и доступ к объектам |
|
||
|
||
Эти функции проверяют вашу конфигурацию во время выполнения и обеспечивают лучшую автодополняемость в IDE и безопасность типов.
|
||
|
||
### Определение объектов
|
||
|
||
Пользовательские объекты описывают как схему, так и поведение записей в вашем рабочем пространстве. Используйте `defineObject()` для определения объектов со встроенной валидацией:
|
||
|
||
```typescript
|
||
// src/app/postCard.object.ts
|
||
import { defineObject, FieldType } from 'twenty-sdk';
|
||
|
||
enum PostCardStatus {
|
||
DRAFT = 'DRAFT',
|
||
SENT = 'SENT',
|
||
DELIVERED = 'DELIVERED',
|
||
RETURNED = 'RETURNED',
|
||
}
|
||
|
||
export default defineObject({
|
||
universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
|
||
nameSingular: 'postCard',
|
||
namePlural: 'postCards',
|
||
labelSingular: 'Post Card',
|
||
labelPlural: 'Post Cards',
|
||
description: 'A post card object',
|
||
icon: 'IconMail',
|
||
fields: [
|
||
{
|
||
universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
|
||
name: 'content',
|
||
type: FieldType.TEXT,
|
||
label: 'Content',
|
||
description: "Postcard's content",
|
||
icon: 'IconAbc',
|
||
},
|
||
{
|
||
universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
|
||
name: 'recipientName',
|
||
type: FieldType.FULL_NAME,
|
||
label: 'Recipient name',
|
||
icon: 'IconUser',
|
||
},
|
||
{
|
||
universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
|
||
name: 'recipientAddress',
|
||
type: FieldType.ADDRESS,
|
||
label: 'Recipient address',
|
||
icon: 'IconHome',
|
||
},
|
||
{
|
||
universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
|
||
name: 'status',
|
||
type: FieldType.SELECT,
|
||
label: 'Status',
|
||
icon: 'IconSend',
|
||
defaultValue: `'${PostCardStatus.DRAFT}'`,
|
||
options: [
|
||
{ value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
|
||
{ value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
|
||
{ value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
|
||
{ value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
|
||
],
|
||
},
|
||
{
|
||
universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
|
||
name: 'deliveredAt',
|
||
type: FieldType.DATE_TIME,
|
||
label: 'Delivered at',
|
||
icon: 'IconCheck',
|
||
isNullable: true,
|
||
defaultValue: null,
|
||
},
|
||
],
|
||
});
|
||
```
|
||
|
||
Основные моменты:
|
||
|
||
* Используйте `defineObject()` для встроенной валидации и лучшей поддержки в IDE.
|
||
* `universalIdentifier` должен быть уникальным и стабильным между развёртываниями.
|
||
* Каждому полю требуются `name`, `type`, `label` и собственный стабильный `universalIdentifier`.
|
||
* Массив `fields` необязателен — вы можете определять объекты без пользовательских полей.
|
||
* Вы можете сгенерировать новые объекты с помощью `yarn app:create-entity`, который проведёт вас через выбор именования, полей и связей.
|
||
|
||
<Note>
|
||
**Базовые поля создаются автоматически.** Когда вы определяете пользовательский объект, Twenty автоматически добавляет стандартные поля, такие как `name`, `createdAt`, `updatedAt`, `createdBy`, `position` и `deletedAt`. Вам не нужно определять их в массиве `fields` — добавляйте только свои пользовательские поля.
|
||
</Note>
|
||
|
||
<Accordion title="Альтернатива: синтаксис на декораторах">
|
||
Вы также можете определять объекты с помощью декораторов TypeScript. Этот подход использует классовый синтаксис с декораторами `@Object`, `@Field` и `@Relation`:
|
||
|
||
```typescript
|
||
import {
|
||
type AddressField,
|
||
Field,
|
||
FieldType,
|
||
type FullNameField,
|
||
Object,
|
||
OnDeleteAction,
|
||
Relation,
|
||
RelationType,
|
||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
|
||
} from 'twenty-sdk';
|
||
import { type Note } from '../../generated';
|
||
|
||
@Object({
|
||
universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
|
||
nameSingular: 'postCard',
|
||
namePlural: 'postCards',
|
||
labelSingular: 'Post card',
|
||
labelPlural: 'Post cards',
|
||
description: 'A post card object',
|
||
icon: 'IconMail',
|
||
})
|
||
export class PostCard {
|
||
@Field({
|
||
universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
|
||
type: FieldType.TEXT,
|
||
label: 'Content',
|
||
description: "Postcard's content",
|
||
icon: 'IconAbc',
|
||
})
|
||
content: string;
|
||
|
||
@Relation({
|
||
universalIdentifier: 'c9e2b4f4-b9ad-4427-9b42-9971b785edfe',
|
||
type: RelationType.ONE_TO_MANY,
|
||
label: 'Notes',
|
||
icon: 'IconComment',
|
||
inverseSideTargetUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note,
|
||
onDelete: OnDeleteAction.CASCADE,
|
||
})
|
||
notes: Note[];
|
||
}
|
||
```
|
||
|
||
Примечание: подход с декораторами требует `experimentalDecorators` в конфигурации TypeScript.
|
||
</Accordion>
|
||
|
||
### Конфигурация приложения (application.config.ts)
|
||
|
||
У каждого приложения есть единственный файл `application.config.ts`, который описывает:
|
||
|
||
* **Что это за приложение**: идентификаторы, отображаемое имя и описание.
|
||
* **Как запускаются его функции**: какую роль они используют для прав доступа.
|
||
* **(Необязательно) переменные**: пары ключ-значение, предоставляемые вашим функциям как переменные окружения.
|
||
|
||
Используйте `defineApp()` для определения конфигурации вашего приложения:
|
||
|
||
```typescript
|
||
// src/app/application.config.ts
|
||
import { defineApp } from 'twenty-sdk';
|
||
import { DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER } from './default-function.role';
|
||
|
||
export default defineApp({
|
||
universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
|
||
displayName: 'My Twenty App',
|
||
description: 'My first Twenty app',
|
||
icon: 'IconWorld',
|
||
applicationVariables: {
|
||
DEFAULT_RECIPIENT_NAME: {
|
||
universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
|
||
description: 'Default recipient name for postcards',
|
||
value: 'Jane Doe',
|
||
isSecret: false,
|
||
},
|
||
},
|
||
functionRoleUniversalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
|
||
});
|
||
```
|
||
|
||
Заметки:
|
||
|
||
* `universalIdentifier` — это детерминированные идентификаторы, которыми вы управляете; сгенерируйте их один раз и сохраняйте стабильными между синхронизациями.
|
||
* `applicationVariables` становятся переменными окружения для ваших функций (например, `DEFAULT_RECIPIENT_NAME` доступна как `process.env.DEFAULT_RECIPIENT_NAME`).
|
||
* `functionRoleUniversalIdentifier` должен соответствовать роли, которую вы определяете в файле `*.role.ts` (см. ниже).
|
||
|
||
#### Роли и разрешения
|
||
|
||
Приложения могут определять роли, инкапсулирующие права на объекты и действия в вашем рабочем пространстве. Поле `functionRoleUniversalIdentifier` в `application.config.ts` обозначает роль по умолчанию, используемую бессерверными функциями вашего приложения.
|
||
|
||
* Ключ API во время выполнения, подставляемый как `TWENTY_API_KEY`, получается из этой роли функции по умолчанию.
|
||
* Типизированный клиент будет ограничен правами, предоставленными этой ролью.
|
||
* Следуйте принципу наименьших привилегий: создайте отдельную роль только с теми правами, которые нужны вашим функциям, и укажите её универсальный идентификатор.
|
||
|
||
##### Роль функции по умолчанию (\*.role.ts)
|
||
|
||
Когда вы генерируете новое приложение, CLI также создаёт файл роли по умолчанию. Используйте `defineRole()` для определения ролей со встроенной валидацией:
|
||
|
||
```typescript
|
||
// src/app/default-function.role.ts
|
||
import { defineRole, PermissionFlag } from 'twenty-sdk';
|
||
|
||
export const DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER =
|
||
'b648f87b-1d26-4961-b974-0908fd991061';
|
||
|
||
export default defineRole({
|
||
universalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
|
||
label: 'Default function role',
|
||
description: 'Default role for function Twenty client',
|
||
canReadAllObjectRecords: false,
|
||
canUpdateAllObjectRecords: false,
|
||
canSoftDeleteAllObjectRecords: false,
|
||
canDestroyAllObjectRecords: false,
|
||
canUpdateAllSettings: false,
|
||
canBeAssignedToAgents: false,
|
||
canBeAssignedToUsers: false,
|
||
canBeAssignedToApiKeys: false,
|
||
objectPermissions: [
|
||
{
|
||
objectNameSingular: 'postCard',
|
||
canReadObjectRecords: true,
|
||
canUpdateObjectRecords: true,
|
||
canSoftDeleteObjectRecords: false,
|
||
canDestroyObjectRecords: false,
|
||
},
|
||
],
|
||
fieldPermissions: [
|
||
{
|
||
objectNameSingular: 'postCard',
|
||
fieldName: 'content',
|
||
canReadFieldValue: false,
|
||
canUpdateFieldValue: false,
|
||
},
|
||
],
|
||
permissionFlags: [PermissionFlag.APPLICATIONS],
|
||
});
|
||
```
|
||
|
||
`universalIdentifier` этой роли затем указывается в `application.config.ts` как `functionRoleUniversalIdentifier`. Иными словами:
|
||
|
||
* **\*.role.ts** определяет, что может делать роль функции по умолчанию.
|
||
* **application.config.ts** указывает на эту роль, чтобы ваши функции наследовали её права.
|
||
|
||
Заметки:
|
||
|
||
* Начните со сгенерированной роли, затем постепенно ограничивайте её, следуя принципу наименьших привилегий.
|
||
* Замените `objectPermissions` и `fieldPermissions` на объекты/поля, которые нужны вашим функциям.
|
||
* `permissionFlags` управляют доступом к возможностям на уровне платформы. Держите их минимальными; добавляйте только то, что нужно.
|
||
* См. рабочий пример в приложении Hello World: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
|
||
|
||
### Конфигурация бессерверной функции и точка входа
|
||
|
||
Каждый файл функции использует `defineFunction()` для экспорта конфигурации с обработчиком и необязательными триггерами. Используйте суффикс файла `*.function.ts` для автоматического обнаружения.
|
||
|
||
```typescript
|
||
// src/app/createPostCard.function.ts
|
||
import { defineFunction } from 'twenty-sdk';
|
||
import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
|
||
import Twenty, { type Person } from '../../generated';
|
||
|
||
const handler = async (
|
||
params:
|
||
| RoutePayload
|
||
| DatabaseEventPayload<ObjectRecordCreateEvent<Person>>
|
||
| CronPayload,
|
||
) => {
|
||
const client = new Twenty(); // generated typed client
|
||
const name = 'name' in params.queryStringParameters
|
||
? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
|
||
: 'Hello world';
|
||
|
||
const result = await client.mutation({
|
||
createPostCard: {
|
||
__args: { data: { name } },
|
||
id: true,
|
||
name: true,
|
||
},
|
||
});
|
||
return result;
|
||
};
|
||
|
||
export default defineFunction({
|
||
universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
|
||
name: 'create-new-post-card',
|
||
timeoutSeconds: 2,
|
||
handler,
|
||
triggers: [
|
||
// Public HTTP route trigger '/s/post-card/create'
|
||
{
|
||
universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
|
||
type: 'route',
|
||
path: '/post-card/create',
|
||
httpMethod: 'GET',
|
||
isAuthRequired: false,
|
||
},
|
||
// Cron trigger (CRON pattern)
|
||
{
|
||
universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
|
||
type: 'cron',
|
||
pattern: '0 0 1 1 *',
|
||
},
|
||
// Database event trigger
|
||
{
|
||
universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
|
||
type: 'databaseEvent',
|
||
eventName: 'person.updated',
|
||
updatedFields: ['name'],
|
||
},
|
||
],
|
||
});
|
||
```
|
||
|
||
Распространённые типы триггеров:
|
||
|
||
* **route**: Публикует вашу функцию по HTTP-пути и методу **под конечной точкой `/s/`**:
|
||
|
||
> например, `path: '/post-card/create',` -> вызов по адресу `<APP_URL>/s/post-card/create`
|
||
|
||
* **cron**: Запускает вашу функцию по расписанию с использованием выражения CRON.
|
||
* **databaseEvent**: Запускается при событиях жизненного цикла объектов рабочего пространства. Когда операция события — `updated`, можно указать конкретные поля для отслеживания в массиве `updatedFields`. Если оставить не заданным или пустым, любое обновление будет вызывать функцию.
|
||
|
||
> например, `person.updated`
|
||
|
||
Заметки:
|
||
|
||
* Массив `triggers` необязателен. Функции без триггеров можно использовать как вспомогательные, вызываемые другими функциями.
|
||
* Вы можете сочетать несколько типов триггеров в одной функции.
|
||
|
||
### Полезная нагрузка триггера маршрута
|
||
|
||
<Warning>
|
||
**Нарушающее совместимость изменение (v1.16, январь 2026):** Формат полезной нагрузки триггера маршрута изменился. До v1.16 параметры запроса, параметры пути и тело передавались напрямую в качестве полезной нагрузки. Начиная с v1.16 они вложены в структурированный объект `RoutePayload`.
|
||
|
||
**До v1.16:**
|
||
|
||
```typescript
|
||
const handler = async (params) => {
|
||
const { param1, param2 } = params; // Direct access
|
||
};
|
||
```
|
||
|
||
**После v1.16:**
|
||
|
||
```typescript
|
||
const handler = async (event: RoutePayload) => {
|
||
const { param1, param2 } = event.body; // Access via .body
|
||
const { queryParam } = event.queryStringParameters;
|
||
const { id } = event.pathParameters;
|
||
};
|
||
```
|
||
|
||
**Чтобы мигрировать существующие функции:** Обновите обработчик, чтобы деструктурировать из `event.body`, `event.queryStringParameters` или `event.pathParameters` вместо прямого доступа к объекту params.
|
||
</Warning>
|
||
|
||
Когда триггер маршрута вызывает вашу функцию, она получает объект `RoutePayload`, соответствующий формату AWS HTTP API v2. Импортируйте тип из `twenty-sdk`:
|
||
|
||
```typescript
|
||
import { defineFunction, type RoutePayload } from 'twenty-sdk';
|
||
|
||
const handler = async (event: RoutePayload) => {
|
||
// Access request data
|
||
const { headers, queryStringParameters, pathParameters, body } = event;
|
||
|
||
// HTTP method and path are available in requestContext
|
||
const { method, path } = event.requestContext.http;
|
||
|
||
return { message: 'Success' };
|
||
};
|
||
```
|
||
|
||
Тип `RoutePayload` имеет следующую структуру:
|
||
|
||
| Свойство | Тип | Описание |
|
||
| ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||
| `headers` | `Record<string, string \| undefined>` | HTTP-заголовки (только перечисленные в `forwardedRequestHeaders`) |
|
||
| `queryStringParameters` | `Record<string, string \| undefined>` | Параметры строки запроса (несколько значений объединяются запятыми) |
|
||
| `pathParameters` | `Record<string, string \| undefined>` | Параметры пути, извлечённые из шаблона маршрута (например, `/users/:id` → `{ id: '123' }`) |
|
||
| `текст` | `object \| null` | Разобранное тело запроса (JSON) |
|
||
| `isBase64Encoded` | `логический тип` | Является ли тело закодированным в base64 |
|
||
| `requestContext.http.method` | `строка` | Метод HTTP (GET, POST, PUT, PATCH, DELETE) |
|
||
| `requestContext.http.path` | `строка` | Необработанный путь запроса |
|
||
|
||
### Проброс HTTP-заголовков
|
||
|
||
По умолчанию HTTP-заголовки из входящих запросов **не** передаются в вашу бессерверную функцию по соображениям безопасности. Чтобы получить доступ к определённым заголовкам, явно перечислите их в массиве `forwardedRequestHeaders`:
|
||
|
||
```typescript
|
||
export default defineFunction({
|
||
universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
|
||
name: 'webhook-handler',
|
||
handler,
|
||
triggers: [
|
||
{
|
||
universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
|
||
type: 'route',
|
||
path: '/webhook',
|
||
httpMethod: 'POST',
|
||
isAuthRequired: false,
|
||
forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
|
||
},
|
||
],
|
||
});
|
||
```
|
||
|
||
В обработчике вы сможете получить доступ к этим заголовкам:
|
||
|
||
```typescript
|
||
const handler = async (event: RoutePayload) => {
|
||
const signature = event.headers['x-webhook-signature'];
|
||
const contentType = event.headers['content-type'];
|
||
|
||
// Validate webhook signature...
|
||
return { received: true };
|
||
};
|
||
```
|
||
|
||
<Note>
|
||
Имена заголовков приводятся к нижнему регистру. Обращайтесь к ним, используя ключи в нижнем регистре (например, `event.headers['content-type']`).
|
||
</Note>
|
||
|
||
Вы можете создать новые функции двумя способами:
|
||
|
||
* **Сгенерировано**: Запустите `yarn app:create-entity` и выберите опцию добавления новой функции. Это создаёт стартовый файл с обработчиком и конфигурацией.
|
||
* **Вручную**: Создайте новый файл `*.function.ts` и используйте `defineFunction()`, следуя тому же шаблону.
|
||
|
||
### Сгенерированный типизированный клиент
|
||
|
||
Запустите yarn app:generate, чтобы создать локальный типизированный клиент в generated/ на основе схемы вашего рабочего пространства. Используйте его в своих функциях:
|
||
|
||
```typescript
|
||
import Twenty from './generated';
|
||
|
||
const client = new Twenty();
|
||
const { me } = await client.query({ me: { id: true, displayName: true } });
|
||
```
|
||
|
||
Клиент повторно генерируется командой `yarn app:generate`. Запускайте повторно после изменения ваших объектов и `yarn app:sync` или при подключении к новому рабочему пространству.
|
||
|
||
#### Учётные данные времени выполнения в бессерверных функциях
|
||
|
||
Когда ваша функция запускается на Twenty, платформа подставляет учётные данные как переменные окружения перед выполнением вашего кода:
|
||
|
||
* `TWENTY_API_URL`: Базовый URL API Twenty, на который нацелено ваше приложение.
|
||
* `TWENTY_API_KEY`: Краткоживущий ключ, ограниченный ролью функции по умолчанию вашего приложения.
|
||
|
||
Заметки:
|
||
|
||
* Вам не нужно передавать URL или ключ API сгенерированному клиенту. Он читает `TWENTY_API_URL` и `TWENTY_API_KEY` из process.env во время выполнения.
|
||
* Права ключа API определяются ролью, на которую ссылается ваш `application.config.ts` через `functionRoleUniversalIdentifier`. Это роль по умолчанию, используемая бессерверными функциями вашего приложения.
|
||
* Приложения могут определять роли, чтобы следовать принципу наименьших привилегий. Выдавайте только те права, которые нужны вашим функциям, затем укажите в `functionRoleUniversalIdentifier` универсальный идентификатор этой роли.
|
||
|
||
### Пример Hello World
|
||
|
||
Посмотрите минимальный сквозной пример, демонстрирующий объекты, функции и несколько триггеров, [здесь](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
|
||
|
||
## Ручная настройка (без генератора)
|
||
|
||
Хотя мы рекомендуем использовать `create-twenty-app` для наилучшего старта, вы также можете настроить проект вручную. Не устанавливайте CLI глобально. Вместо этого добавьте `twenty-sdk` как локальную зависимость и настройте скрипты в вашем package.json:
|
||
|
||
```bash filename="Terminal"
|
||
yarn add -D twenty-sdk
|
||
```
|
||
|
||
Затем добавьте скрипты, подобные этим:
|
||
|
||
```json filename="package.json"
|
||
{
|
||
"scripts": {
|
||
"auth": "twenty auth login",
|
||
"generate": "twenty app generate",
|
||
"dev": "twenty app dev",
|
||
"sync": "twenty app sync",
|
||
"uninstall": "twenty app uninstall",
|
||
"logs": "twenty app logs",
|
||
"create-entity": "twenty app add",
|
||
"help": "twenty --help"
|
||
}
|
||
}
|
||
```
|
||
|
||
Теперь вы можете запускать те же команды через Yarn, например, `yarn app:dev`, `yarn app:sync` и т. д.
|
||
|
||
## Устранение неполадок
|
||
|
||
* Ошибки аутентификации: выполните `yarn auth:login` и убедитесь, что у вашего ключа API есть необходимые права.
|
||
* Не удаётся подключиться к серверу: проверьте URL API и доступность сервера Twenty.
|
||
* Отсутствующие/устаревшие типы или клиент: выполните `yarn app:generate`, затем `yarn app:dev`.
|
||
* Режим разработки не синхронизируется: убедитесь, что запущен `yarn app:dev`, и что ваша среда не игнорирует изменения.
|
||
|
||
Канал помощи в Discord: https://discord.com/channels/1130383047699738754/1130386664812982322
|