github-actions[bot]
a3a6a55051
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
189 lines
13 KiB
Plaintext
189 lines
13 KiB
Plaintext
---
|
||
title: Kurulum Kancaları
|
||
description: Kurulum, yükseltme veya kaldırma yaşam döngüsü sırasında mantık çalıştırın — başlangıç verilerini yükleyin, kayıtları yedekleyin, yükseltmeyi doğrulayın, harici kaynakları temizleyin.
|
||
icon: wrench
|
||
---
|
||
|
||
Kurulum kancaları, kurulum, yükseltme veya kaldırma yaşam döngüsü sırasında çalışan özel mantık işlevleridir. Bunlar, normal [mantık işlevleri](/l/tr/developers/extend/apps/logic/logic-functions) ile aynı işleyici çalışma zamanını paylaşır, ancak kendi tanımlama işlevleriyle bildirilirler ve normal tetikleyici modelinin (HTTP, cron, veritabanı olayları) dışında yaşarlar. Kurulum kancaları bir `InstallPayload` alır (`{ previousVersion?: string; newVersion: string }` — yeni bir kurulumda `previousVersion`, `undefined` olur); kaldırma kancası ise bir `UninstallPayload` alır (`{ version?: string }` — kaldırılan sürüm).
|
||
|
||
Her uygulama, her bir kanca türünden (kurulum öncesi, kurulum sonrası, kaldırma) **en fazla bir tane** tanımlayabilir. Her türden birden fazla tespit edilirse manifest derlemesi hata verir.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ install flow │
|
||
│ │
|
||
│ upload package → [pre-install] → metadata migration → │
|
||
│ generate SDK → [post-install] │
|
||
│ │
|
||
│ old schema visible new schema visible │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Bir bakışta
|
||
|
||
| | `definePreInstallLogicFunction` | `definePostInstallLogicFunction` |
|
||
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
|
||
| Çalışma zamanı | Üstveri geçişinden önce — **önceki** şema ve veriler hâlâ sağlamdır | Geçişten ve SDK oluşturmasından sonra — **yeni** şema yürürlüktedir |
|
||
| Yürütme | Her zaman senkron; kurulumu bloke eder | Varsayılan olarak asenkron (kuyruğa alınır, 3 yeniden deneme); `shouldRunSynchronously: true` ile isteğe bağlı senkron |
|
||
| Başarısızlık durumunda | Kurulum, herhangi bir şema değişikliğinden önce **iptal edilir** | Asenkron: en fazla 3 kez yeniden denenir. Senkron: çağıran `POST_INSTALL_ERROR` alır (şema değişiklikleri **geri alınmaz**) |
|
||
| Tipik kullanım | Bir geçişin kaybedeceği verileri yedeklemek veya düzeltmek; hata fırlatarak riskli bir yükseltmeyi reddetmek | Varsayılan verileri tohumlamak, çalışma alanını yapılandırmak, harici kaynakları kaydetmek |
|
||
|
||
**Kural:** varsayılan olarak post-install kullanın. Yalnızca geçişin kendisi yıkıcıysa ve önceki durum yok olmadan önce onu yakalamanız gerekiyorsa kurulum öncesine başvurun.
|
||
|
||
| Şunu yapmak istiyorsunuz... | Kullan |
|
||
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||
| Verileri tohumlamak, çalışma alanını yapılandırmak, harici kaynakları kaydetmek | `post-install` |
|
||
| Kurulum yanıtını engellememesi gereken uzun süreli işleri yürütmek | `post-install` (varsayılan asenkron mod, worker yeniden denemeleriyle) |
|
||
| Kurulum döndükten hemen sonra çağıranın güveneceği hızlı kurulumu gerçekleştirmek | `post-install` ile `shouldRunSynchronously: true` |
|
||
| Yaklaşan geçişin kaybedeceği verileri okumak veya yedeklemek | `pre-install` |
|
||
| Mevcut verileri bozacak bir yükseltmeyi reddetmek | `pre-install` (işleyiciden hata fırlatmak) |
|
||
| Her yükseltmede uzlaştırma çalıştırmak | `shouldRunOnVersionUpgrade: true` ile her iki kancadan biri |
|
||
|
||
## Her iki kanca tarafından paylaşılan davranış
|
||
|
||
* Yapılandırma, tetikleyici ayarları çıkarılmış bir `defineLogicFunction` yapılandırmasıdır ve buna ek olarak `shouldRunOnVersionUpgrade` içerir.
|
||
* **Ne zaman çalışır**: varsayılan olarak yalnızca ilk kurulumlarda. Yükseltmelerde de çalışması için `shouldRunOnVersionUpgrade: true` olarak ayarlayın. Yükseltme yoluna göre dallanmak için `previousVersion` / `newVersion` kullanın.
|
||
* **İdempotans önemlidir**: asenkron post-install yeniden denenebilir ve `shouldRunOnVersionUpgrade` açıkken her iki kanca da yükseltmelerde yeniden çalıştırılır.
|
||
* Alışıldık mantık işlevi ortamı (`APPLICATION_ID`, `APP_ACCESS_TOKEN`, `API_URL`) enjekte edilir, böylece Twenty API'sini uygulamanızın jetonuyla çağırabilirsiniz.
|
||
* Kanca, derleme zamanında otomatik olarak uygulama manifestine (`preInstallLogicFunction` / `postInstallLogicFunction`) eklenir — [`defineApplication()`](/l/tr/developers/extend/apps/config/application) içinde referans verilecek bir şey yoktur.
|
||
* Varsayılan `timeoutSeconds`, veri tohumlama gibi daha uzun kurulum görevlerine izin vermek için 300 olarak ayarlanmıştır.
|
||
* **Geliştirme modunda yürütülmez**: `yarn twenty dev` kurulum akışını atlar ve dosyaları doğrudan senkronize eder, bu nedenle kancalar burada asla çalışmaz. Bunları bunun yerine manuel olarak tetikleyin:
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty dev:function:exec --postInstall
|
||
yarn twenty dev:function:exec --preInstall
|
||
```
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="definePostInstallLogicFunction" description="Çalışma alanı üstveri (metadata) geçişi uygulanıp tamamlandıktan sonra çalışır">
|
||
|
||
Uygulamanızın kurulumu tamamlandıktan sonra bir kez çalışır: üstveri senkronize edilmiştir, SDK istemcisi oluşturulmuştur, yeni şema sorgulanabilir durumdadır. Örnek — ilk kurulumlarda varsayılan bir kaydı tohumlamak:
|
||
|
||
```ts src/logic-functions/post-install.ts
|
||
import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
|
||
import { CoreApiClient } from 'twenty-client-sdk/core';
|
||
|
||
const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
|
||
if (previousVersion) return; // fresh installs only
|
||
|
||
const client = new CoreApiClient();
|
||
await client.mutation({
|
||
createPostCard: {
|
||
__args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },
|
||
id: true,
|
||
},
|
||
});
|
||
};
|
||
|
||
export default definePostInstallLogicFunction({
|
||
universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
|
||
name: 'post-install',
|
||
description: 'Seeds a welcome post card after install.',
|
||
timeoutSeconds: 300,
|
||
shouldRunOnVersionUpgrade: false,
|
||
shouldRunSynchronously: false,
|
||
handler,
|
||
});
|
||
```
|
||
|
||
`shouldRunSynchronously` bayrağı yürütme modelini kontrol eder:
|
||
|
||
* `false` *(varsayılan)* — mesaj kuyruğuna alınır (`retryLimit: 3`) ve bir worker tarafından çalıştırılır. Kurulum yanıtı, iş kuyruğa alınır alınmaz döner. **Uzun süreli işler için kullanın** — büyük veri kümelerinin tohumlanması, yavaş üçüncü taraf API'leri.
|
||
* `true` — kurulum akışı sırasında satır içi olarak yürütülür. Kurulum isteği, işleyici bitene kadar bloke olur; fırlatılan bir hata, çağırana `POST_INSTALL_ERROR` olarak yansır (yeniden deneme yoktur). **Hızlı ve yanıt dönmeden önce mutlaka tamamlanması gereken işler için kullanın.** Bu noktada geçiş zaten uygulanmıştır, bu nedenle bir hata şema değişikliklerini geri almaz — yalnızca hatayı görünür kılar.
|
||
|
||
</Accordion>
|
||
<Accordion title="definePreInstallLogicFunction" description="Çalışma alanı üstveri (metadata) geçişi uygulanmadan önce çalışır">
|
||
|
||
Üstveri geçişinden önce, **önceki** şemaya karşı çalışır — bir geçişin kaybedeceği verileri yedeklemek veya riskli bir yükseltmeyi reddetmek için doğru yerdir. Çalıştırmadan önce, sunucu yalnızca ekleyici bir "indirgenmiş eşitleme" yürütür; bu, yalnızca yeni sürümün kurulum öncesi işlevini kaydeder, diğer her şey — önceki sürümün nesneleri, alanları ve verileri — işleyiciniz çalıştığında dokunulmadan kalır.
|
||
|
||
Kurulum öncesi her zaman **senkron**dur ve kurulumu bloke eder. İşleyici bir hata fırlatırsa, herhangi bir şema değişikliğinden önce kurulum iptal edilir — çalışma alanı, tutarlı bir durumda önceki sürümde kalır. Bu kasıtlıdır: kurulum öncesi, riskli bir yükseltmeyi reddetmek için son şansınızdır.
|
||
|
||
Örnek — geçiş onu düşürmeden önce eski bir alanın değerlerini kopyalamak:
|
||
|
||
```ts src/logic-functions/pre-install.ts
|
||
import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
|
||
import { CoreApiClient } from 'twenty-client-sdk/core';
|
||
|
||
const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
|
||
// Only the 1.x → 2.x upgrade drops the legacy `notes` field.
|
||
if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
|
||
return;
|
||
}
|
||
|
||
const client = new CoreApiClient();
|
||
const { postCards } = await client.query({
|
||
postCards: {
|
||
__args: { filter: { notes: { isNot: null } } },
|
||
edges: { node: { id: true, notes: true } },
|
||
},
|
||
});
|
||
|
||
// Copy legacy `notes` into `description` before the migration drops the
|
||
// column. If this fails, the upgrade aborts and the workspace stays on v1.
|
||
for (const { node } of postCards.edges) {
|
||
await client.mutation({
|
||
updatePostCard: {
|
||
__args: { id: node.id, data: { description: node.notes } },
|
||
id: true,
|
||
},
|
||
});
|
||
}
|
||
};
|
||
|
||
export default definePreInstallLogicFunction({
|
||
universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
|
||
name: 'pre-install',
|
||
description: 'Backs up legacy notes into description before the v2 migration.',
|
||
timeoutSeconds: 300,
|
||
shouldRunOnVersionUpgrade: true,
|
||
handler,
|
||
});
|
||
```
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## Kaldırma kancası
|
||
|
||
`defineUninstallLogicFunction`, bir kullanıcı uygulamanızı kaldırdığında çalışan bir kancayı bildirir. Bu kanca, uygulamanın üst verileri, verileri ve kodu kaldırılmadan **önce** çalışır — silme geçişi (migration) çalıştıktan sonra çalıştırılacak hiçbir şey kalmaz — bu nedenle işleyiciniz uygulamanın nesnelerini ve kayıtlarını hâlâ sorgulayabilir. Bunu harici kaynakların temizliği için kullanın: API kaynaklarının tahsisini geri alın, kalan botları silin, web kancalarını (webhook) iptal edin.
|
||
|
||
Notlar:
|
||
|
||
* Kanca, en iyi gayret esasına göre çalışır: senkron olarak çalışır, ancak bir hata günlüğe kaydedilir ve **kaldırmayı asla engellemez** — temizleme, bir uygulamanın kaldırılamaz hale gelmesine neden olmamalıdır.
|
||
* Kaldırma kancası, `UninstallPayload` alır (`{ version?: string }` — kaldırılan sürüm).
|
||
* Başarısız olan yeni bir kurulum geri alındığında çalışmaz — uygulama kurulumunu hiçbir zaman tamamlamamıştır.
|
||
* Kanca, uygulama kaldırıldıktan sonra çalışamaz; bu nedenle, uygulama verilerine bağlı olan harici temizlik (örneğin kayıtlarda saklanan bot kimlikleri) harici zamanlanmış bir işte değil, burada yapılmalıdır.
|
||
* Kurulum kancalarında olduğu gibi, bu kanca da **geliştirme modunda çalıştırılmaz** — bunun yerine manuel olarak tetikleyin:
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty dev:function:exec --uninstall
|
||
```
|
||
|
||
```ts src/logic-functions/uninstall.ts
|
||
import { defineUninstallLogicFunction, type UninstallPayload } from 'twenty-sdk/define';
|
||
import { CoreApiClient } from 'twenty-client-sdk/core';
|
||
|
||
const handler = async (_payload: UninstallPayload): Promise<void> => {
|
||
const client = new CoreApiClient();
|
||
const { meetingBots } = await client.query({
|
||
meetingBots: { edges: { node: { id: true, externalBotId: true } } },
|
||
});
|
||
|
||
// Delete the provider-side bots so nothing keeps recording after uninstall.
|
||
for (const { node } of meetingBots.edges) {
|
||
await fetch(`https://api.recorder.example/bots/${node.externalBotId}`, {
|
||
method: 'DELETE',
|
||
headers: { Authorization: `Bearer ${process.env.RECORDER_API_KEY}` },
|
||
});
|
||
}
|
||
};
|
||
|
||
export default defineUninstallLogicFunction({
|
||
universalIdentifier: 'b2c3d4e5-6789-01bc-def0-234567890abc',
|
||
name: 'uninstall',
|
||
description: 'Deletes remaining recorder bots when the app is uninstalled.',
|
||
timeoutSeconds: 300,
|
||
handler,
|
||
});
|
||
```
|