input، وتمرر النتائج إلى الخطوات اللاحقة عبر الدالة output.set().
متى تستخدم «تشغيل برنامج نصي» بدلًا من الإجراءات المدمجة
عمومًا، استخدم الإجراءات المدمجة عندما تلبي احتياجاتك. واستخدم «تشغيل برنامج نصي» عندما تحتاج إلى منطق مخصص أو تحويل بيانات أو تفاعل معقد مع واجهات API.
البيئة
كيفية الإعداد
- أضف إجراء تشغيل برنامج نصي إلى سير العمل.
- يفتح محرر البرنامج النصي بمساحة فارغة. اكتب شيفرة JavaScript هنا.
- يستطيع البرنامج النصي قراءة بيانات الخطوات السابقة باستخدام كائن
input(راجع أدناه). - استخدم
output.set(key, value)لتمرير النتائج إلى الخطوات اللاحقة. - (اختياري) أضف تبعيات npm في لوحة التهيئة إذا كان البرنامج النصي يحتاج إلى مكتبات خارجية.
- انقر على اختبار لتشغيل البرنامج النصي ببيانات حقيقية من أحدث تنفيذ للمشغّل.
- تحقق من مخرجات الاختبار وسجلات وحدة التحكم للتأكد من عمل البرنامج النصي بصورة صحيحة.
- احفظ الإجراء.
قراءة بيانات الإدخال
يحتوي كائنinput على بيانات جميع الخطوات السابقة في سير العمل. تُحدد كل خطوة بمعرّف الإجراء الخاص بها.
بنية الإدخال
الحصول على بيانات المشغّل (حقول السجل)
الحصول على بيانات من خطوة جلب السجلات
الحصول على بيانات من مخرجات إجراءات أخرى
كتابة المخرجات
استخدمoutput.set(key, value) لإتاحة البيانات للخطوات اللاحقة. ويمكنك تعيين عدة مفاتيح.
output.set("status", "success")، فيمكن للخطوة التالية الإشارة إلى status في مخرجات هذا البرنامج النصي.
تصحيح الأخطاء باستخدام console.log
أثناء التطوير، استخدمconsole.log() لفحص البيانات وتتبع تدفق التنفيذ. تظهر مخرجات السجل في لوحة الاختبار عند النقر على اختبار.
إدارة حزم npm
يمكنك استخدام حزم npm في برامجك النصية. أعلن عن التبعيات في لوحة التهيئة:require():
المتغيرات المدمجة
الأمان: نطاق AUTOMATION_TOKEN
يُنشأAUTOMATION_TOKEN تلقائيًا لكل تشغيل للأتمتة. ويحمل صلاحيات منشئ الأتمتة نفسها، ويقتصر نطاقه على التنفيذ الحالي. النقاط الأساسية:
- يستطيع الوصول إلى أي جدول يمكن لمنشئ الأتمتة الوصول إليه.
- يظل صالحًا طوال مدة تنفيذ البرنامج النصي فقط (مهلة 60 ثانية).
- لا تكشف هذا الرمز للأنظمة الخارجية؛ فهو مخصص لاستدعاء واجهة Teable API من داخل برنامجك النصي.
استدعاء واجهة Teable API
استدعاء الذكاء الاصطناعي من برنامج نصي
يرسلPOST /api/automation/runtime/ai مطالبة إلى نموذج الذكاء الاصطناعي في قاعدة بياناتك. تُستمد قاعدة البيانات من سياق الأتمتة، ولذلك لا يلزم معرّف قاعدة بيانات. يتلقى النص prompt، بالإضافة إلى attachments وmodelKey وtemperature وoutputType الاختيارية؛ وتكون الاستجابة { "message": ... }.
المرفقات هي عناصر { url, mimetype, name }، بحد أقصى 10 عناصر لكل استدعاء، وحجم أقل من 20MB لكل عنصر، ومدة تنزيل لا تتجاوز 30 ثانية، وتشمل الصور وملفات PDF ومستندات Office. قد لا يتمكن نموذج الدردشة الافتراضي من قراءة الصور والمرفقات المشابهة، لذا مرر modelKey عند إرسال الملفات. يستهلك كل استدعاء رصيدًا.
معالجة الأخطاء
ضع دائمًا العمليات المحفوفة بالمخاطر داخل كتل try/catch حتى يتمكن سير العمل من معالجة حالات الفشل بسلاسة:مثال كامل: معالجة تذاكر الدعم وتوجيهها
نصائح
- ابدأ باستخدام console.log. عند إنشاء برنامج نصي جديد، سجّل كائن
inputبالكامل أولًا لفهم بنيته. - حافظ على تركيز البرامج النصية. نفّذ مهمة واحدة بإتقان بدلًا من حشر عدة مهام في برنامج واحد. ويمكنك تسلسل عدة إجراءات لتشغيل برنامج نصي عند الحاجة.
- انتبه إلى مهلة 60 ثانية. قد تبلغ العمليات الطويلة (معالجة بيانات كثيرة أو استدعاءات API متسلسلة عديدة) حد المهلة. قسّم المهام الكبيرة إلى أجزاء أصغر.
- اختبر باستخدام بيانات حقيقية. تستخدم لوحة الاختبار بيانات فعلية من أحدث تنفيذ للمشغّل، مما يمنحك نتائج واقعية.
- عالج البيانات المفقودة. استخدم القيم الافتراضية (العامل
||) للحقول التي قد تكون فارغة أو غير معرّفة.
موضوعات ذات صلة
- الإنشاء بالذكاء الاصطناعي — لمهام الذكاء الاصطناعي المستندة إلى المطالبات التي لا تحتاج إلى شيفرة مخصصة
- طلب HTTP — لاستدعاءات API البسيطة التي لا تحتاج إلى برمجة نصية

