defineLogicFunction
عرّف الدوال المنطقية ومشغّلاتها
defineLogicFunction
عرّف الدوال المنطقية ومشغّلاتها
كل ملف وظيفة يستخدم أنواع المشغّلات المتاحة:يحتوي نوع
في معالجك، يمكنك الوصول إلى الرؤوس المُمرَّرة بهذه الطريقة:لأسباب أمنية، يتم تقييد ترويسات الاستجابة بقائمة مسموح بها. يتم إسقاط أي ترويسة ليست في القائمة (مثل تتضمن الحمولة ما يلي:
في عمليات الحذف اللين (soft deletes)، يتبع مثال على حدث الإنشاء:مثال على حدث التحديث:تشغيل المشغّل فقط عند تحديثات البريد الإلكتروني:مثال على حدث الحذف:النقاط الرئيسية:
defineLogicFunction() لتصدير تكوين مع معالج ومشغّلات اختيارية.src/logic-functions/createPostCard.logic-function.ts
- httpRoute: يعرِض وظيفتك على مسار وطريقة HTTP تحت نقطة النهاية
/s/:
مثال:path: '/post-card/create'يمكن استدعاؤه عبرhttps://your-twenty-server.com/s/post-card/create
لاستدعاء دالة منطقية يتم تشغيلها بواسطة مسار من مكون واجهة (بدون واجهة رسومية)، راجع قسم استدعاء دالة منطقية.
- cron: يشغّل وظيفتك على جدول باستخدام تعبير CRON.
- databaseEvent: يعمل على أحداث دورة حياة كائنات مساحة العمل. عندما تكون عملية الحدث هي
updated، يمكن تحديد الحقول المحددة المراد الاستماع إليها في مصفوفةupdatedFields. إذا تُركت غير معرّفة أو فارغة، فسيؤدي أي تحديث إلى تشغيل الدالة.
مثال:person.updated،*.created،company.*
يمكنك أيضًا تنفيذ دالة يدويًا باستخدام CLI:يمكنك متابعة السجلات باستخدام:
حمولة مشغل المسار
عندما يستدعي مُشغِّل المسار وظيفتك المنطقية، فإنها تتلقّى كائنRoutePayload الذي يتبع صيغة AWS HTTP API v2.
استورد نوع RoutePayload من twenty-sdk/logic-function:RoutePayload على البنية التالية:| الخاصية | النوع | الوصف | مثال |
|---|---|---|---|
headers | Record\<string, string | undefined> | رؤوس HTTP (فقط تلك المدرجة في forwardedRequestHeaders) | انظر القسم أدناه |
queryStringParameters | Record\<string, string | undefined> | معلمات سلسلة الاستعلام (تُضمّ القيم المتعددة باستخدام فواصل) | /users?ids=1&ids=2&ids=3&name=Alice -> { ids: '1,2,3', name: 'Alice' } |
pathParameters | Record\<string, string | undefined> | معلمات المسار المستخرجة من نمط المسار | /users/:id, /users/123 -> { id: '123' } |
body | object | null | جسم الطلب المُحلَّل (JSON) | { id: 1 } -> { id: 1 } |
rawBody | string | undefined | نص الطلب الأصلي بترميز UTF-8، قبل تحليل JSON. مفيد للتحقق من تواقيع خطافات الويب على نمط HMAC (مثل X-Hub-Signature-256 الخاص بـ GitHub وStripe). undefined عندما لم يحتفظ وقت التشغيل بها. | |
isBase64Encoded | boolean | ما إذا كان جسم الطلب مُرمَّزًا بترميز base64 | |
requestContext.http.method | string | طريقة HTTP (GET, POST, PUT, PATCH, DELETE) | |
requestContext.http.path | string | المسار الخام للطلب |
forwardedRequestHeaders
افتراضيًا، لا تُمرَّر رؤوس HTTP من الطلبات الواردة إلى دالتك المنطقية لأسباب أمنية. للوصول إلى رؤوس محددة، أدرِجها في مصفوفةforwardedRequestHeaders:تُحوَّل أسماء الرؤوس إلى أحرف صغيرة. يمكنك الوصول إليها باستخدام مفاتيح بأحرف صغيرة (على سبيل المثال،
event.headers['content-type']).استجابة HTTP مخصصة
بشكل افتراضي، فإن إرجاع قيمة بسيطة من المعالج الخاص بك يعيدها كاستجابة200 (بصيغة JSON للكائنات وtext/plain للسلاسل النصية). للتحكم في رمز الحالة ورؤوس الاستجابة، أعد كائن Response من twenty-sdk/logic-function:Set-Cookie، وترويسات CORS مثل Access-Control-Allow-Origin، أو ترويسات X-* المخصصة) بصمت قبل إرسال الاستجابة. ترويسات الاستجابة المسموح بها هي:content-typecontent-languagecontent-dispositioncache-controlretry-after
يجب أن يكون رمز الحالة رمز حالة HTTP صالحًا (بين 100 و599). تتم مطابقة أسماء ترويسات الاستجابة دون حساسية لحالة الأحرف.
حمولة مُحفِّز حدث قاعدة البيانات
عندما يستدعي مُحفِّز حدث قاعدة البيانات دالة المنطق الخاصة بك، فإنه يستقبل كائنDatabaseEventPayload واحدًا لكل سجل تم تغييره. تجمع الحمولة بين البيانات الوصفية حول مساحة العمل والكائن المصدر وبين الحدث على مستوى السجل.| الخاصية | الوصف |
|---|---|
name | اسم الحدث، مثل person.updated. |
workspaceId | مساحة العمل التي وقع فيها الحدث. |
objectMetadata | بيانات وصفية للكائن الذي تم تغييره. |
recordId | معرّف السجل الذي تم تغييره. |
userId, userWorkspaceId, workspaceMemberId | حقول الفاعل عندما يكون الحدث ناتجًا عن مستخدم في مساحة العمل. |
properties | بيانات السجل الخاصة بالحدث، مع before وafter وdiff وupdatedFields اعتمادًا على العملية. |
| حدث | بيانات السجل |
|---|---|
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 بنية نمط التحديث لأن حقل deletedAt في السجل يتغيّر.
في عمليات الحذف الدائم، استخدم .destroyed.databaseEventTriggerSettings.updatedFields يرشّح أيّ أحداث التحديث التي تُشغِّل الدالة.
event.properties.updatedFields يوضّح لك أي الحقول تغيّرت فعليًا في الحدث الحالي.إتاحة دالة كأداة ذكاء اصطناعي أو كإجراء ضمن سير العمل
يمكن إتاحة دوال المنطق على واجهتين، ولكلٍ منهما مشغِّل خاص به:toolTriggerSettings— يجعل الدالة قابلة للاكتشاف عبر ميزات الذكاء الاصطناعي الخاصة بـ Twenty (الدردشة، MCP، استدعاء الدوال). يستخدم JSON Schema القياسي، وهو التنسيق الذي تفهمه LLMs أصلاً.workflowActionTriggerSettings— يجعل الدالة تظهر كخطوة في منشئ سير العمل المرئي. يستخدمInputSchemaالغني الخاص بـ Twenty لكي يتمكن المُنشئ من عرض محرّرات الحقول المناسبة، وأدوات انتقاء المتغيّرات، والتسميات.
cronTriggerSettings وdatabaseEventTriggerSettings وhttpRouteTriggerSettings — النمط نفسه، والشكل نفسه.src/logic-functions/enrich-company.logic-function.ts
- يمكن للدالة مزج الواجهات — صرِّح بكلٍ من
toolTriggerSettingsوworkflowActionTriggerSettingsلإتاحتها في الدردشة وفي منشئ سير العمل. toolTriggerSettings.inputSchemaوworkflowActionTriggerSettings.inputSchemaكلاهما اختياري. عند الإغفال، يستنتج مُنشئ البيان هذه المخططات من الشيفرة المصدرية للمعالج (JSON Schema لأداة الذكاء الاصطناعي، وInputSchemaالخاصة بـ Twenty لإجراء سير العمل). قدّم واحدًا صراحةً عندما ترغب في أنواع أكثر ثراءً — على سبيل المثال، مع حقول واعية بـFieldMetadataTypeمثلCURRENCYأوRELATIONلمنشئ سير العمل، أو مع حقولdescriptionالتي يمكن لوكيل الذكاء الاصطناعي قراءتها:
اكتب
description جيدًا. يعتمد وكلاء الذكاء الاصطناعي على حقل description الخاص بالدالة لتحديد وقت استخدام الأداة. كن محددًا بشأن ما تفعله الأداة ومتى ينبغي استدعاؤها.خطافات التثبيت — معالجات ما قبل التثبيت وما بعد التثبيت — تشترك في وقت التشغيل نفسه، ولكن يُصرَّح عنها بدوال تعريف خاصة بها ولا تأخذ إعدادات المشغّلات. راجع خطافات التثبيت (Install Hooks) لمعرفة
definePreInstallLogicFunction و definePostInstallLogicFunction.عملاء واجهة برمجة تطبيقات مضبوطة الأنواع (twenty-client-sdk)
توفر حزمة twenty-client-sdk عميلين لـ GraphQL ذوي أنواع ثابتة للتفاعل مع واجهة Twenty البرمجية من وظائفك المنطقية ومكوّنات الواجهة الأمامية.
| العميل | استيراد | نقطة النهاية | مُولَّد؟ |
|---|---|---|---|
CoreApiClient | twenty-client-sdk/core | /graphql — بيانات مساحة العمل (السجلات، الكائنات) | نعم، في وقت التطوير/البناء |
MetadataApiClient | twenty-client-sdk/metadata | /metadata — تكوين مساحة العمل، رفع الملفات | لا، يأتي مُجهزًا مسبقًا |
CoreApiClient
استعلام وتعديل بيانات مساحة العمل (السجلات، الكائنات)
CoreApiClient
استعلام وتعديل بيانات مساحة العمل (السجلات، الكائنات)
CoreApiClient هو العميل الرئيسي للاستعلام وتعديل بيانات مساحة العمل. يُولَّد من مخطط مساحة العمل لديك أثناء yarn twenty dev أو yarn twenty dev:build، لذا فهو مضبوط الأنواع بالكامل ليتوافق مع كائناتك وحقولك.true لتضمين حقل، واستخدم __args للوسيطات، وعشّش الكائنات للعلاقات. ستحصل على إكمال تلقائي كامل وفحص للأنواع يعتمد على مخطط مساحة العمل لديك.يتم توليد CoreApiClient في وقت التطوير/البناء. إذا استخدمته دون تشغيل
yarn twenty dev أو yarn twenty dev:build أولًا، فسيؤدي ذلك إلى خطأ. تحدث عملية التوليد تلقائيًا — إذ يستطلع CLI مخطط GraphQL لمساحة عملك وينشئ عميلًا مضبوط الأنواع باستخدام @genql/cli.استخدام CoreSchema للتعليقات التوضيحية للأنواع
CoreSchema يوفّر أنواع TypeScript المطابقة لكائنات مساحة العمل لديك — مفيد لتعيين أنواع حالة المكوّن أو معاملات الدوال:MetadataApiClient
إعدادات مساحة العمل، والتطبيقات، ورفع الملفات
MetadataApiClient
إعدادات مساحة العمل، والتطبيقات، ورفع الملفات
يأتي
النقاط الرئيسية:
MetadataApiClient مُجهّزًا مسبقًا مع SDK (لا حاجة للتوليد). يستعلم عن نقطة النهاية /metadata للحصول على تكوين مساحة العمل والتطبيقات ورفع الملفات.رفع الملفات
يتضمنMetadataApiClient طريقة uploadFile لإرفاق الملفات بالحقول من نوع الملف:| المعلمة | النوع | الوصف |
|---|---|---|
fileBuffer | Buffer | المحتوى الخام للملف |
filename | string | اسم الملف (يُستخدم للتخزين والعرض) |
contentType | string | نوع MIME (القيمة الافتراضية application/octet-stream إذا لم يُحدَّد) |
fieldMetadataUniversalIdentifier | string | قيمة universalIdentifier لحقل نوع الملف في كائنك |
- يستخدم
universalIdentifierالخاص بالحقل (وليس معرّفه الخاص بمساحة العمل)، بحيث يعمل كود الرفع لديك عبر أي مساحة عمل مُثبَّت فيها تطبيقك. - العنوان
urlالمُعاد هو عنوان URL موقّع يمكنك استخدامه للوصول إلى الملف المرفوع.
عند تشغيل كودك على Twenty (وظائف منطقية أو مكوّنات أمامية)، يقوم النظام الأساسي بحقن بيانات الاعتماد كمتغيرات بيئية:
TWENTY_API_URL— عنوان URL الأساسي لواجهة Twenty البرمجيةTWENTY_APP_ACCESS_TOKEN— مفتاح قصير العمر ذو نطاق يقتصر على الدور الافتراضي لوظيفة تطبيقك
process.env. تُحدَّد أذونات مفتاح واجهة برمجة التطبيقات بواسطة الدور المُعلن باستخدام defineApplicationRole() (أو المشار إليه عبر defaultRoleUniversalIdentifier في application-config.ts).