Skip to main content
نوصي بشدة باستخدام «تشغيل برنامج نصي» لإنشاء عمليات الأتمتة، لأنه يستطيع تغطية جميع سلوكيات الإجراءات، بما فيها الإجراءات التي كان يلزم إنشاؤها يدويًا لولا ذلك. ما عليك سوى وصف متطلباتك للذكاء الاصطناعي في الدردشة.يُرجى ملاحظة أنه إذا أضفت إجراءات يدويًا، فلن يتعرف عليها الذكاء الاصطناعي أو يعدّلها لاحقًا.
يتيح لك إجراء «تشغيل برنامج نصي» كتابة JavaScript مخصص لمعالجة منطق لا تستطيع الإجراءات المدمجة تغطيته. يمكنك تحويل البيانات، واستدعاء واجهات API خارجية، وإجراء الحسابات، وتنفيذ التفرع الشرطي، وغير ذلك، وكل هذا داخل بيئة اختبار معزولة وآمنة. تستقبل البرامج النصية بيانات الخطوات السابقة عبر كائن input، وتمرر النتائج إلى الخطوات اللاحقة عبر الدالة output.set().

متى تستخدم «تشغيل برنامج نصي» بدلًا من الإجراءات المدمجة

عمومًا، استخدم الإجراءات المدمجة عندما تلبي احتياجاتك. واستخدم «تشغيل برنامج نصي» عندما تحتاج إلى منطق مخصص أو تحويل بيانات أو تفاعل معقد مع واجهات API.

البيئة

كيفية الإعداد

  1. أضف إجراء تشغيل برنامج نصي إلى سير العمل.
  2. يفتح محرر البرنامج النصي بمساحة فارغة. اكتب شيفرة JavaScript هنا.
  3. يستطيع البرنامج النصي قراءة بيانات الخطوات السابقة باستخدام كائن input (راجع أدناه).
  4. استخدم output.set(key, value) لتمرير النتائج إلى الخطوات اللاحقة.
  5. (اختياري) أضف تبعيات npm في لوحة التهيئة إذا كان البرنامج النصي يحتاج إلى مكتبات خارجية.
  6. انقر على اختبار لتشغيل البرنامج النصي ببيانات حقيقية من أحدث تنفيذ للمشغّل.
  7. تحقق من مخرجات الاختبار وسجلات وحدة التحكم للتأكد من عمل البرنامج النصي بصورة صحيحة.
  8. احفظ الإجراء.

قراءة بيانات الإدخال

يحتوي كائن input على بيانات جميع الخطوات السابقة في سير العمل. تُحدد كل خطوة بمعرّف الإجراء الخاص بها.

بنية الإدخال

الحصول على بيانات المشغّل (حقول السجل)

الحصول على بيانات من خطوة جلب السجلات

الحصول على بيانات من مخرجات إجراءات أخرى

استخدم console.log(JSON.stringify(input, null, 2)) أثناء الاختبار لرؤية البنية الدقيقة لبيانات الإدخال. وهذه أسرع طريقة لفهم ما هو متاح.

كتابة المخرجات

استخدم output.set(key, value) لإتاحة البيانات للخطوات اللاحقة. ويمكنك تعيين عدة مفاتيح.
يصبح كل مفتاح تعيّنه متغيرًا مستقلًا يمكن للخطوات اللاحقة الإشارة إليه عبر منتقي المتغيرات +. على سبيل المثال، إذا استدعيت output.set("status", "success")، فيمكن للخطوة التالية الإشارة إلى status في مخرجات هذا البرنامج النصي.

تصحيح الأخطاء باستخدام console.log

أثناء التطوير، استخدم console.log() لفحص البيانات وتتبع تدفق التنفيذ. تظهر مخرجات السجل في لوحة الاختبار عند النقر على اختبار.
لا تظهر سجلات وحدة التحكم إلا أثناء الاختبار، ولا تظهر في سجل تشغيل الإنتاج. استخدمها بحرية أثناء إنشاء برنامجك النصي.

إدارة حزم npm

يمكنك استخدام حزم npm في برامجك النصية. أعلن عن التبعيات في لوحة التهيئة:
ثم استخدمها في البرنامج النصي بواسطة require():
فضّل ميزات JavaScript المدمجة على حزم npm متى أمكن. تتضمن JavaScript الحديثة أدوات كثيرة، مثل Array.map() وArray.filter() وObject.entries() والقوالب النصية والتفكيك، وغيرها. لا تضف حزم npm إلا عندما تقدم قيمة ملموسة.

المتغيرات المدمجة

الأمان: نطاق 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 حتى يتمكن سير العمل من معالجة حالات الفشل بسلاسة:
دون معالجة الأخطاء، سيؤدي فشل طلب fetch أو ورود تنسيق بيانات غير متوقع إلى تعطل البرنامج النصي، ولن تتلقى الخطوات اللاحقة أي مخرجات.

مثال كامل: معالجة تذاكر الدعم وتوجيهها

نصائح

  • ابدأ باستخدام console.log. عند إنشاء برنامج نصي جديد، سجّل كائن input بالكامل أولًا لفهم بنيته.
  • حافظ على تركيز البرامج النصية. نفّذ مهمة واحدة بإتقان بدلًا من حشر عدة مهام في برنامج واحد. ويمكنك تسلسل عدة إجراءات لتشغيل برنامج نصي عند الحاجة.
  • انتبه إلى مهلة 60 ثانية. قد تبلغ العمليات الطويلة (معالجة بيانات كثيرة أو استدعاءات API متسلسلة عديدة) حد المهلة. قسّم المهام الكبيرة إلى أجزاء أصغر.
  • اختبر باستخدام بيانات حقيقية. تستخدم لوحة الاختبار بيانات فعلية من أحدث تنفيذ للمشغّل، مما يمنحك نتائج واقعية.
  • عالج البيانات المفقودة. استخدم القيم الافتراضية (العامل ||) للحقول التي قد تكون فارغة أو غير معرّفة.

موضوعات ذات صلة

  • الإنشاء بالذكاء الاصطناعي — لمهام الذكاء الاصطناعي المستندة إلى المطالبات التي لا تحتاج إلى شيفرة مخصصة
  • طلب HTTP — لاستدعاءات API البسيطة التي لا تحتاج إلى برمجة نصية
آخر تعديل في ٤ سبتمبر ٢٠٢٦