defineLogicFunction
Definujte logické funkce a jejich spouštěče
defineLogicFunction
Definujte logické funkce a jejich spouštěče
Každý soubor funkce používá Dostupné typy spouštěčů:Typ
Ve vašem handleru k přeposlaným záhlavím přistupujte takto:Z bezpečnostních důvodů jsou hlavičky odpovědi omezeny na seznam povolených položek. Jakákoli hlavička, která není na seznamu (např. Tělo zprávy obsahuje:
U logických smazání má Příklad události vytvoření:Příklad události aktualizace:Spouštění pouze při aktualizacích e‑mailu:Příklad události smazání:Hlavní body:
defineLogicFunction() k exportu konfigurace s obslužnou funkcí (handlerem) a volitelnými spouštěči.src/logic-functions/createPostCard.logic-function.ts
- httpRoute: Zpřístupní vaši funkci na HTTP cestě a metodě pod koncovým bodem
/s/:
např.path: '/post-card/create'je volatelné nahttps://your-twenty-server.com/s/post-card/create
Chcete-li vyvolat logickou funkci spuštěnou trasou z (bezhlavé) front-endové komponenty, podívejte se na Volání logické funkce.
- cron: Spouští vaši funkci podle plánu pomocí výrazu CRON.
- databaseEvent: Spouští se při událostech životního cyklu objektů v pracovním prostoru. Když je operace události
updated, lze konkrétní sledovaná pole určit v poliupdatedFields. Pokud zůstane nedefinované nebo prázdné, spustí funkci jakákoli aktualizace.
např.person.updated,*.created,company.*
Funkci můžete také spustit ručně pomocí CLI:Logy můžete sledovat pomocí:
Payload spouštěče trasy
Když spouštěč typu route vyvolá vaši logickou funkci, ta obdrží objektRoutePayload, který odpovídá
AWS HTTP API v2 formátu.
Importujte typ RoutePayload z twenty-sdk/logic-function:RoutePayload má následující strukturu:| Vlastnost | Typ | Popis | Příklad |
|---|---|---|---|
headers | Record\<string, string | undefined> | Záhlaví HTTP (pouze ta uvedená v forwardedRequestHeaders) | viz sekci níže |
queryStringParameters | Record\<string, string | undefined> | Parametry query stringu (více hodnot spojených čárkami) | /users?ids=1&ids=2&ids=3&name=Alice -> { ids: '1,2,3', name: 'Alice' } |
pathParameters | Record\<string, string | undefined> | Parametry cesty extrahované ze vzoru trasy | /users/:id, /users/123 -> { id: '123' } |
body | object | null | Parsované tělo požadavku (JSON) | { id: 1 } -> { id: 1 } |
rawBody | string | undefined | Původní tělo požadavku v UTF-8, před parsováním JSONu. Užitečné pro ověřování podpisů webhooků typu HMAC (např. GitHubův X-Hub-Signature-256, Stripe). undefined, pokud jej běhové prostředí nezachovalo. | |
isBase64Encoded | boolean | Zda je tělo kódováno base64 | |
requestContext.http.method | string | Metoda HTTP (GET, POST, PUT, PATCH, DELETE) | |
requestContext.http.path | string | Nezpracovaná cesta požadavku |
forwardedRequestHeaders
Ve výchozím nastavení se záhlaví HTTP z příchozích požadavků z bezpečnostních důvodů do vaší logické funkce ne předávají. Chcete-li zpřístupnit konkrétní záhlaví, výslovně je uveďte v poliforwardedRequestHeaders:Názvy záhlaví jsou normalizovány na malá písmena. Přistupujte k nim pomocí klíčů s malými písmeny (například
event.headers['content-type']).Vlastní odpověď HTTP
Ve výchozím nastavení vrácení prosté hodnoty z vašeho handleru odešle tuto hodnotu zpět jako odpověď200 (JSON pro objekty, text/plain pro řetězce). Pro kontrolu stavového kódu a hlaviček odpovědi vraťte Response z twenty-sdk/logic-function:Set-Cookie, CORS hlavičky jako Access-Control-Allow-Origin nebo vlastní hlavičky X-*), je tiše zahozena před odesláním odpovědi. Povolené hlavičky odpovědi jsou:content-typecontent-languagecontent-dispositioncache-controlretry-after
Stavový kód musí být platný stavový kód HTTP (mezi 100 a 599). Názvy hlaviček odpovědi se porovnávají bez rozlišení velikosti písmen.
Payload spouštěče databázové události
Když spouštěč databázové události vyvolá vaši logickou funkci, obdrží jedenDatabaseEventPayload pro každý změněný záznam. Payload kombinuje metadata o zdrojovém pracovním prostoru a objektu s událostí na úrovni záznamu.| Vlastnost | Popis |
|---|---|
name | Název události, například person.updated. |
workspaceId | Pracovní prostor, ve kterém k události došlo. |
objectMetadata | Metadata objektu, který se změnil. |
recordId | ID změněného záznamu. |
userId, userWorkspaceId, workspaceMemberId | Pole aktéra, pokud byla událost způsobena uživatelem pracovního prostoru. |
properties | Data záznamu pro událost, s before, after, diff a updatedFields v závislosti na operaci. |
| Událost | Data záznamu |
|---|---|
person.created | event.properties.after |
person.updated | event.properties.before, event.properties.after, event.properties.diff, event.properties.updatedFields |
person.destroyed | event.properties.before |
.deleted podobu jako u aktualizace, protože se změní pole deletedAt záznamu.
Pro trvalá smazání použijte .destroyed.databaseEventTriggerSettings.updatedFields filtruje, které události aktualizace spustí funkci.
event.properties.updatedFields říká, která pole se v aktuální události skutečně změnila.Zpřístupnění funkce jako nástroje AI nebo akce pracovního postupu
Logické funkce lze zpřístupnit na dvou rozhraních, z nichž každé má vlastní spouštěč:toolTriggerSettings— zpřístupní funkci AI funkcím Twenty (chat, MCP, volání funkcí). Používá standardní JSON Schema, formát, kterému modely LLM nativně rozumějí.workflowActionTriggerSettings— zobrazí funkci jako krok ve vizuálním builderu workflow. Používá bohatéInputSchemaod Twenty, aby builder mohl vykreslit správné editory polí, voliče proměnných a štítky.
cronTriggerSettings, databaseEventTriggerSettings a httpRouteTriggerSettings — stejný vzor, stejná struktura.src/logic-functions/enrich-company.logic-function.ts
- Funkce může míchat rozhraní — deklarujte jak
toolTriggerSettings, takworkflowActionTriggerSettings, abyste ji zpřístupnili v chatu i ve workflow builderu. toolTriggerSettings.inputSchemaaworkflowActionTriggerSettings.inputSchemajsou obě volitelné. Pokud jsou vynechány, sestavovač manifestu je odvodí ze zdrojového kódu handleru (JSON Schema pro nástroj AI,InputSchemaod Twenty pro akci workflow). Uveďte jej explicitně, když chcete bohatší typování — například u polí s podporouFieldMetadataType, jakoCURRENCYneboRELATIONpro workflow builder, nebo s polidescription, která si AI agent může přečíst:
Napište kvalitní
description. Agenti AI se spoléhají na pole funkce description při rozhodování, kdy nástroj použít. Buďte konkrétní ohledně toho, co nástroj dělá a kdy se má volat.Instalační hooky — předinstalační a poinstalační handlery — sdílejí toto běhové prostředí, ale deklarují se vlastními funkcemi
define a nepřebírají nastavení spouštěče (triggeru). Viz Instalační hooky pro definePreInstallLogicFunction a definePostInstallLogicFunction.Typovaní klienti API (twenty-client-sdk)
Balíčektwenty-client-sdk poskytuje dva typované klienty GraphQL pro práci s Twenty API z vašich logických funkcí a frontendových komponent.
| Klient | Importovat | Koncový bod | Generováno? |
|---|---|---|---|
CoreApiClient | twenty-client-sdk/core | /graphql — data pracovního prostoru (záznamy, objekty) | Ano, při vývoji/sestavení |
MetadataApiClient | twenty-client-sdk/metadata | /metadata — konfigurace pracovního prostoru, nahrávání souborů | Ne, dodává se předem sestavený |
CoreApiClient
Dotazování a změny dat pracovního prostoru (záznamy, objekty)
CoreApiClient
Dotazování a změny dat pracovního prostoru (záznamy, objekty)
CoreApiClient je hlavní klient pro dotazování a mutace dat pracovního prostoru. Generuje se z vašeho schématu pracovního prostoru během yarn twenty dev nebo yarn twenty dev:build, takže je plně typovaný tak, aby odpovídal vašim objektům a polím.true zahrnete pole, pro argumenty použijte __args a pro relace vnořujte objekty. Získáte plné automatické doplňování a kontrolu typů založené na schématu vašeho pracovního prostoru.CoreApiClient je generován při vývoji/sestavení. Pokud jej použijete bez předchozího spuštění
yarn twenty dev nebo yarn twenty dev:build, vyvolá chybu. Generování probíhá automaticky — CLI prozkoumá GraphQL schéma vašeho pracovního prostoru a vygeneruje typovaného klienta pomocí @genql/cli.Použití CoreSchema pro anotace typů
CoreSchema poskytuje typy TypeScriptu odpovídající objektům vašeho pracovního prostoru — hodí se pro typování stavu komponent nebo parametrů funkcí:MetadataApiClient
Konfigurace pracovního prostoru, aplikace a nahrávání souborů
MetadataApiClient
Konfigurace pracovního prostoru, aplikace a nahrávání souborů
MetadataApiClient je dodáván předem sestavený v rámci SDK (není vyžadováno žádné generování). Odesílá dotazy na endpoint /metadata pro konfiguraci pracovního prostoru, aplikace a nahrávání souborů.Nahrávání souborů
MetadataApiClient obsahuje metodu uploadFile pro připojování souborů k polím typu souboru:| Parametr | Typ | Popis |
|---|---|---|
fileBuffer | Buffer | Surový obsah souboru |
filename | string | Název souboru (používá se pro ukládání a zobrazení) |
contentType | string | Typ MIME (pokud je vynechán, výchozí je application/octet-stream) |
fieldMetadataUniversalIdentifier | string | universalIdentifier pole typu souboru ve vašem objektu |
- Používá
universalIdentifierpole (nikoli jeho ID specifické pro pracovní prostor), takže váš kód pro nahrávání funguje v jakémkoli pracovním prostoru, kde je vaše aplikace nainstalována. - Vrácená hodnota
urlje podepsaná adresa URL, kterou můžete použít k přístupu k nahranému souboru.
Když váš kód běží na Twenty (logické funkce nebo frontendové komponenty), platforma vloží přihlašovací údaje jako proměnné prostředí:
TWENTY_API_URL— Základní URL Twenty APITWENTY_APP_ACCESS_TOKEN— krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace
process.env. Oprávnění API klíče jsou určena rolí deklarovanou pomocí defineApplicationRole() (nebo odkazovanou prostřednictvím defaultRoleUniversalIdentifier v application-config.ts).