defineLogicFunction
Mantık işlevlerini ve tetikleyicilerini tanımlayın
defineLogicFunction
Mantık işlevlerini ve tetikleyicilerini tanımlayın
Her işlev dosyası, bir işleyici ve isteğe bağlı tetikleyiciler içeren bir yapılandırmayı dışa aktarmak için Kullanılabilir tetikleyici türleri:
İşleyicinizde, iletilen başlıklara şu şekilde erişin:Güvenlik nedenleriyle, yanıt üstbilgileri bir izin listesiyle sınırlandırılmıştır. Listede yer almayan herhangi bir üstbilgi (örneğin Fonksiyona şu adresten erişilebilir:Her iki tanımlayıcı da manifest’inizdeki
Çözümlenen değer geçerli bir çalışma alanı UUID’si olmalı ve uygulamanızın o çalışma alanına yüklü olması gerekir, aksi halde istek, fonksiyon çalışmadan önce reddedilir.Çoğu sağlayıcı HMAC-SHA256 ile imzalar; farklı olan kısımlar başlık adı, özet kodlaması ve imzalanan payload dizesidir. Birkaç örnek:
Yük, şunları içerir:
Yumuşak silmeler için, kayıt Oluşturma olayı örneği:Güncelleme olayı örneği:Yalnızca e-posta güncellemelerinde tetikle:Yok etme olayı örneği:Önemli noktalar:Parametrelerinizi bir kez tanımlayıp her iki yüzeyde de kullanmak için tek bir JSON Şeması (
defineLogicFunction() kullanır.src/logic-functions/createPostCard.logic-function.ts
- httpRoute: İşlevinizi bir HTTP yolu ve yöntemiyle
/s/uç noktasının altında kullanıma sunar:
örn.path: '/post-card/create'https://your-twenty-server.com/s/post-card/createadresinden çağrılabilir
Arayüzsüz bir ön uç bileşeninden rota tarafından tetiklenen mantık fonksiyonunu çağırmak için bkz. Mantık fonksiyonu çağırma.
- cron: Bir CRON ifadesi kullanarak işlevinizi bir zamanlamayla çalıştırır.
- databaseEvent: Çalışma alanı nesnesi yaşam döngüsü olaylarında çalışır. Olay işlemi
updatedolduğunda, dinlenecek belirli alanlarupdatedFieldsdizisinde belirtilebilir. Tanımsız veya boş bırakılırsa, herhangi bir güncelleme işlevi tetikler.
örn.person.updated,*.created,company.*
- serverWebhook: Üçüncü taraf bir hizmetten (Stripe, GitHub, Svix, …) gelen webhook’ları alır tek bir kayıt kapsamlı uç noktadan ve hedef çalışma alanını payload’dan çözümler. Sunucu webhook tetikleyicisine bakın.
Bir işlevi CLI kullanarak manuel olarak da çalıştırabilirsiniz:Günlükleri şu şekilde izleyebilirsiniz:
Rota tetikleyicisi yükü
Bir rota tetikleyicisi mantık fonksiyonunuzu çağırdığında, AWS HTTP API v2 formatını izleyen birRoutePayload nesnesi alır.
RoutePayload türünü twenty-sdk/logic-function içinden içe aktarın:RoutePayload türünün yapısı şu şekildedir:| Özellik | Tür | Açıklama | Örnek |
|---|---|---|---|
headers | Record\<string, string | undefined> | HTTP başlıkları (forwardedRequestHeaders içinde listelenenlerle sınırlı) | aşağıdaki bölüme bakın |
queryStringParameters | Record\<string, string | undefined> | Sorgu dizesi parametreleri (birden çok değer virgülle birleştirilir) | /users?ids=1&ids=2&ids=3&name=Alice -> { ids: '1,2,3', name: 'Alice' } |
pathParameters | Record\<string, string | undefined> | Rota deseninden çıkarılan yol parametreleri | /users/:id, /users/123 -> { id: '123' } |
body | object | null | Ayrıştırılmış istek gövdesi (JSON) | { id: 1 } -> { id: 1 } |
rawBody | string | undefined | JSON ayrıştırılmadan önceki özgün UTF-8 istek gövdesi. HMAC tarzı webhook imzalarını doğrulamak için kullanışlıdır (ör. GitHub’ın X-Hub-Signature-256, Stripe). Çalışma zamanı onu korumadığında undefined olur. | |
isBase64Encoded | boolean | Gövdenin base64 ile kodlanıp kodlanmadığı | |
requestContext.http.method | string | HTTP yöntemi (GET, POST, PUT, PATCH, DELETE) | |
requestContext.http.path | string | Ham istek yolu |
forwardedRequestHeaders
Varsayılan olarak, güvenlik nedenleriyle gelen isteklerden HTTP başlıkları mantık fonksiyonunuza aktarılmaz. Belirli başlıklara erişmek için bunlarıforwardedRequestHeaders dizisinde listeleyin:Başlık adları küçük harfe normalize edilir. Onlara küçük harfli anahtarlarla erişin (örneğin,
event.headers['content-type']).Özel HTTP yanıtı
Varsayılan olarak, işleyicinizden düz bir değer döndürmek, onu200 yanıtı olarak geri gönderir (nesneler için JSON, stringler için text/plain). Durum kodunu ve yanıt üstbilgilerini kontrol etmek için, twenty-sdk/logic-function içinden bir Response döndürün:Set-Cookie, Access-Control-Allow-Origin gibi CORS üstbilgileri veya özel X-* üstbilgileri), yanıt gönderilmeden önce sessizce yok sayılır. İzin verilen yanıt üstbilgileri şunlardır:content-typecontent-languagecontent-dispositioncache-controlretry-after
Durum kodu geçerli bir HTTP durum kodu olmalıdır (100 ile 599 arasında). Yanıt üstbilgisi adları büyük/küçük harfe duyarsız olarak eşleştirilir.
Sunucu webhook tetikleyicisi
httpRouteTriggerSettings, /s/ altında bir fonksiyon sunar ve çalışma alanını istek ana bilgisayarından çözümler — bu da her çalışma alanının kendi alan adına sahip olduğu durumda işe yarar. Üçüncü taraf sağlayıcılar ise, her kiracının olaylarını tek webhook URL’sine iletir. Bu durum için serverWebhookTriggerSettings kullanın: fonksiyona kayıt kapsamlı bir uç noktadan erişilebilir ve çalışma alanı, payload’dan çözümlenir.src/logic-functions/handle-provider-webhook.logic-function.ts
universalIdentifier değerleridir — uygulama kaydınınki ve bu mantık fonksiyonununki. Bu URL’yi sağlayıcıya kaydedin.Çalışma alanı çözümleme. Tek bir uç nokta her çalışma alanına hizmet verdiğinden, entegrasyonunuz hedef workspaceId değerini teslimatta bir yere koymalı ve workspaceIdResolver.{ source, path } platforma bunun nereden okunacağını söyler:| Alan | Değerler | Notlar |
|---|---|---|
source | body | query | header | body, ayrıştırılmış JSON’u okur. query en evrensel seçenektir — genellikle kaydettiğiniz callback URL’sini kontrol edersiniz, bu yüzden ?twentyWorkspaceId=… ekleyin. |
path | nokta-yolu, örn. metadata.twentyWorkspaceId | Alfasayısal / _ / - segmentleriyle sınırlandırılmıştır; prototype anahtarları reddedilir. |
| Sağlayıcı | İletilecek başlıklar | İmzalanmış dize | Özet |
|---|---|---|---|
| Svix (Recall, Resend, Clerk) | webhook-id, webhook-timestamp, webhook-signature | {id}.{timestamp}.{rawBody} | base64 (gizli anahtar, whsec_ kaldırıldıktan sonra base64’tür) |
| Stripe | stripe-signature | {timestamp}.{rawBody} | hex |
| GitHub | x-hub-signature-256 | {rawBody} | hex (sha256= önekiyle) |
| Shopify | x-shopify-hmac-sha256 | {rawBody} | base64 |
| Slack | x-slack-signature, x-slack-request-timestamp | v0:{timestamp}:{rawBody} | hex (v0= önekiyle) |
Fonksiyon senkron olarak çalışır ve döndürdüğünüz değer HTTP yanıtı olur, bu nedenle sağlayıcılar durum kodunuzu görür ve 2xx olmayanlarda yeniden deneyebilir. İşleyicileri hızlı tutun — bazı sağlayıcılar (örn. Slack) birkaç saniye içinde zaman aşımına uğrar. Fonksiyon imza denetlenmeden önce çalıştığı için, bu uç noktayı edge’inizde hız sınırlamasıyla koruyun.
Veritabanı olay tetikleyicisi yükü
Bir veritabanı olay tetikleyicisi mantık fonksiyonunuzu çağırdığında, değişen her kayıt için birDatabaseEventPayload alır. Yük, kaynak çalışma alanı ve nesne hakkındaki üstveriyi, kayıt düzeyindeki olayla birleştirir.| Özellik | Açıklama |
|---|---|
name | person.updated gibi bir olay adı. |
workspaceId | Olayın gerçekleştiği çalışma alanı. |
objectMetadata | Değişen nesne için üstveri. |
recordId | Değişen kaydın kimliği. |
userId, userWorkspaceId, workspaceMemberId | Olay bir çalışma alanı kullanıcısı tarafından tetiklendiğinde aktör alanları. |
properties | İşleme bağlı olarak before, after, diff ve updatedFields içeren olay için kayıt verileri. |
| Etkinlik | Kayıt verileri |
|---|---|
person.created | event.properties.after |
person.updated | event.properties.before, event.properties.after, event.properties.diff, event.properties.updatedFields |
person.destroyed | event.properties.before |
deletedAt alanı değiştiğinden .deleted, güncelleme tarzı yapıyı izler.
Kalıcı silmeler için .destroyed kullanın.databaseEventTriggerSettings.updatedFields, hangi güncelleme olaylarının fonksiyonu tetikleyeceğini filtreler.
event.properties.updatedFields, mevcut olayda hangi alanların gerçekten değiştiğini size bildirir.Bir işlevi bir yapay zekâ aracı veya iş akışı eylemi olarak kullanıma sunma
Mantık işlevleri, her birinin kendi tetikleyicisi olacak şekilde iki yerde kullanılabilir hâle getirilebilir:toolTriggerSettings— işlevi Twenty’nin yapay zekâ özellikleri (sohbet, MCP, işlev çağırma) tarafından bulunabilir hâle getirir. Standart JSON Şeması’nı kullanır; LLM’lerin doğal olarak anladığı biçimdir.workflowActionTriggerSettings— işlevin görsel iş akışı oluşturucusunda bir adım olarak görünmesini sağlar. Oluşturucunun uygun alan düzenleyicilerini, değişken seçicilerini ve etiketleri oluşturabilmesi için Twenty’nin zenginInputSchema’sını kullanır.
cronTriggerSettings, databaseEventTriggerSettings ve httpRouteTriggerSettings ile birlikte yer alır — aynı desen, aynı biçim.src/logic-functions/enrich-company.logic-function.ts
- Bir işlev yüzeyleri karıştırabilir — onu sohbette VE iş akışı oluşturucusunda kullanıma sunmak için hem
toolTriggerSettingshem deworkflowActionTriggerSettingsbildirin. toolTriggerSettings.inputSchemaveworkflowActionTriggerSettings.inputSchemaikisi de isteğe bağlıdır. Atlandığında, manifest oluşturucu bunları işleyici kaynak kodundan çıkarır (yapay zekâ aracı için JSON Şeması, iş akışı eylemi için Twenty’ninInputSchema’sı). Daha zengin tipleme istediğinizde birini açıkça belirtin — örneğin, iş akışı oluşturucu içinFieldMetadataType’ı bilenCURRENCYveyaRELATIONgibi alanlarla ya da yapay zekâ aracısının okuyabileceğidescriptionalanlarıyla:
InputJsonSchema) oluşturun ve bunu iş akışı eylemi için twenty-sdk/logic-function içindeki jsonSchemaToInputSchema ile dönüştürün. toolTriggerSettings.inputSchema, JSON Şemasını doğrudan alırken workflowActionTriggerSettings.inputSchema, Twenty’nin InputSchema tipini bekler:İyi bir
description yazın. AI ajanları, aracı ne zaman kullanacaklarına karar vermek için işlevin description alanına güvenir. Aracın ne yaptığını ve ne zaman çağrılması gerektiğini açıkça belirtin.Çalışma zamanı yardımcıları.
twenty-sdk/utils, işleyicilerin doğrudan twenty-shared içinden içe aktarma yapmasına gerek kalmaması için küçük çalışma zamanı yardımcılarını yeniden dışa aktarır. Örneğin, isDefined(value) hem null hem de undefined için false döndürür — bunu, çalışma zamanında T | undefined olarak yazılmış olsa bile null olarak gelebilen isteğe bağlı işleyici girdilerini güvenli şekilde daraltmak için kullanın:Yükleme kancaları — ön yükleme ve yükleme sonrası işleyiciler — bu çalışma zamanını paylaşır ancak kendi tanımlama işlevleriyle bildirilir ve tetikleyici ayarlarını almaz.
definePreInstallLogicFunction ve definePostInstallLogicFunction için Yükleme Kancaları bölümüne bakın.Tipli API istemcileri (twenty-client-sdk)
twenty-client-sdk paketi, mantık fonksiyonlarınızdan ve ön uç bileşenlerinizden Twenty API ile etkileşim kurmak için tip tanımlı iki GraphQL istemcisi sağlar.
| İstemci | İçe Aktar | Uç nokta | Oluşturuldu mu? |
|---|---|---|---|
CoreApiClient | twenty-client-sdk/core | /graphql — çalışma alanı verileri (kayıtlar, nesneler) | Evet, geliştirme/derleme zamanında |
MetadataApiClient | twenty-client-sdk/metadata | /metadata — çalışma alanı yapılandırması, dosya yüklemeleri | Hayır, önceden hazırlanmış olarak gelir |
CoreApiClient
Çalışma alanı verilerini sorgulayın ve değiştirin (kayıtlar, nesneler)
CoreApiClient
Çalışma alanı verilerini sorgulayın ve değiştirin (kayıtlar, nesneler)
CoreApiClient, çalışma alanı verilerini sorgulamak ve değiştirmek için ana istemcidir. yarn twenty dev veya yarn twenty dev:build sırasında çalışma alanı şemanızdan oluşturulur, bu nedenle nesnelerinize ve alanlarınıza uyacak şekilde tamamen tiplenmiştir.true geçin, bağımsız değişkenler için __args kullanın ve ilişkiler için nesneleri iç içe yerleştirin. Çalışma alanı şemanıza göre tam otomatik tamamlama ve tip denetimi elde edersiniz.CoreApiClient geliştirme/derleme zamanında oluşturulur. Bunu önce
yarn twenty dev veya yarn twenty dev:build çalıştırmadan kullanırsanız, bir hata verir. Oluşturma otomatik olarak gerçekleşir — CLI, çalışma alanınızın GraphQL şemasını inceler ve @genql/cli kullanarak tiplenmiş bir istemci üretir.Tür açıklamaları için CoreSchema’yı kullanma
CoreSchema, çalışma alanı nesnelerinize uyan TypeScript türleri sağlar — bileşen durumunu veya işlev parametrelerini tiplemek için kullanışlıdır:MetadataApiClient
Çalışma alanı yapılandırması, uygulamalar ve dosya yüklemeleri
MetadataApiClient
Çalışma alanı yapılandırması, uygulamalar ve dosya yüklemeleri
MetadataApiClient, SDK ile birlikte önceden hazırlanmış olarak gelir (oluşturma gerektirmez). Çalışma alanı yapılandırması, uygulamalar ve dosya yüklemeleri için /metadata uç noktasını sorgular.Dosya yükleme
MetadataApiClient, dosya türündeki alanlara dosya eklemek için bir uploadFile yöntemi içerir:| Parametre | Tür | Açıklama |
|---|---|---|
fileBuffer | Buffer | Dosyanın ham içeriği |
filename | string | Dosyanın adı (depolama ve görüntüleme için kullanılır) |
contentType | string | MIME türü (belirtilmezse varsayılan olarak application/octet-stream kullanılır) |
fieldMetadataUniversalIdentifier | string | Nesnenizdeki dosya türü alanının universalIdentifier değeri |
- Alan için
universalIdentifierkullanır (çalışma alanına özgü kimliği değil), böylece yükleme kodunuz uygulamanızın yüklü olduğu herhangi bir çalışma alanında çalışır. - Döndürülen
url, yüklenen dosyaya erişmek için kullanabileceğiniz imzalı bir URL’dir.
Kodunuz Twenty üzerinde çalıştığında (mantık işlevleri veya ön uç bileşenleri), platform kimlik bilgilerini ortam değişkenleri olarak enjekte eder:
TWENTY_API_URL— Twenty API’nin temel URL’siTWENTY_APP_ACCESS_TOKEN— Uygulamanızın varsayılan işlev rolü kapsamında kısa ömürlü bir anahtar
process.env’den okurlar. API anahtarının izinleri, defineApplicationRole() ile bildirilen role (veya application-config.ts içindeki defaultRoleUniversalIdentifier üzerinden referans verilen role) göre belirlenir.