التوثيق

البرامج النصية / استيراد البيانات القديمة

"Scripts" هو الحل الشامل الذي تقدمه SKOOR لإنشاء البرامج النصية وتحريرها وتشغيلها، مع العديد من الخيارات لتخصيصها.

صفحة Scripts

تنقسم الصفحة إلى ثلاثة أقسام رئيسية:

الإعدادات

يتضمن هذا القسم الإعدادات العامة للنص البرمجي، مثل:

الإعداد

الوصف

الاسم

حدد اسم البرنامج النصي SKOOR.

الوصف

حدد وصف البرنامج النصي SKOOR.

مهلة الانتظار

يحدد مهلة الانتظار الافتراضية لتنفيذ البرنامج النصي، بالثواني.

أنواع MIME المقبولة

يحدد أنواع MIME المسموح بها لملفات المصدر التي يتم تحميلها.

تكوين التشغيل الافتراضي

يحدد تكوين التشغيل الافتراضي الذي يعمل به البرنامج النصي.

نسخ الرمز المميز وإعادة تعيينه

يسمح للمسؤولين بنسخ رمز الويب هوك وإعادة تعيينه. متاح فقط للمسؤولين (ADMINS).

تكوينات الجدولة

يسمح بجدولات متعددة مع تكوينات تشغيل مخصصة.

اختر أولاً فترة (سنة، شهر، أسبوع، يوم، ساعة، أو دقيقة) – بناءً على اختيارك، ستظهر الحقول ذات الصلة فقط (الأشهر، أيام الشهر، أيام الأسبوع، الساعات، الدقائق). يمكن تحديد خيارات متعددة، ولتشغيل العملية على فترات منتظمة، اضبط الفترة وانقر نقرًا مزدوجًا على الرقم المطلوب.

مثال: كل يوم في الساعة 02:30 → الفترة "اليوم"، الساعة 2، الدقيقة 30.

مثال: كل 10 دقائق → الفترة "ساعة"، الدقيقة <انقر نقرًا مزدوجًا على 10>

تشغيل التكوينات

يسمح بتخصيص مهلة الانتظار ومتغيرات البيئة.

image-20260512-100658.png

الملفات

يقدم هذا القسم حلاً كاملاً لإدارة الملفات الخاصة بالبرنامج النصي، بما في ذلك محرر متطور للبيانات النصية.

سيتم عرض رابط تنزيل إذا كانت البيانات ثنائية (غير قابلة للتحرير في شكل نصي).

image-20250214-093009.png

التشغيل

هذا القسم مسؤول عن تشغيل البرنامج النصي ومراقبة عمليات تشغيله. ويوفر منطقة سحب وإفلات صغيرة لتحميل الملفات المصدرية إذا لزم الأمر.

image-20261015-083557.png

دعم شريط التقدم

يمكن للبرامج النصية عرض شريط التقدم في كل من مربع حوار تفاصيل المهمة وعنصر واجهة المستخدم الخاص بالبرنامج النصي. لتحديث التقدم، يجب أن يصدر البرنامج النصي رسائل حالة تشير إلى الخطوة الحالية وإجمالي الخطوات المتوقعة. تستخدم تحديثات الحالة التنسيق التالي:

#PROGRESS: {step}/{maxSteps}

يتم تحليل الأسطر المطابقة لهذا التنسيق تلقائيًا لتحديث شريط التقدم ويتم استبعادها من إخراج السجل القياسي للنص البرمجي.

يوضح المثال التالي كيفية إرسال تحديثات التقدم:

import os
import time

max_count = int(os.environ.get('max_count', 10))

for i in range(1, max_count + 1):
    time.sleep(1)
    print(f"#PROGRESS: {i}/{max_count}")
    print(f"Reached {(i / max_count) * 100:.1f}%")
image-20261015-085633.png

إنشاء برنامج نصي

يمكن إنشاء البرامج النصية يدويًا أو تحميلها عبر ملفات Zip كما هو موضح أدناه:

image-20250423-061036.png
image-20250423-061102.png

استيراد البرنامج النصي باستخدام ملف مضغوط

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

image-20260731-130509.png

الإعداد

الوصف

تأكيد الكتابة فوق

تشير إلى وجود نص برمجي يحمل نفس الاسم.
سيؤدي تحديد هذه العلامة إلى استبدال النص البرمجي المذكور.

تضمين بيانات تعريف البرنامج النصي

يشير إلى أن ملف Zip يحتوي على ملف script_metadata.json:

يتضمن هذا الملف المهلة الافتراضية للبرنامج النصي ووصفه وتكوين التشغيل/الجدولة.

أركان البرنامج النصي

برنامج التشغيل

يحتوي الملف الرئيسي على منطق البرنامج النصي. وهذا يحدد نوع المشغل للبرنامج النصي:

  • يتوقع برنامج تشغيل Python وجود ملف main.py.

  • يتوقع برنامج تشغيل Talend وجود ملف <scriptName>_run.sh.

  • يتوقع مشغل Shell وجود ملف run.sh.

ضع البرنامج النصي الرئيسي في مستوى واحد أسفل الجذر (أو أعلى)، لأن المسح من حيث العرض يستخدم دائمًا البرنامج النصي الأقل عمقًا الذي يعثر عليه.

تظهر الرسالة التالية عند محاولة تشغيل برنامج نصي بدون برنامج تشغيل رئيسي.

image-20250423-061703.png

.env

إنه ملف نصي بسيط يتضمن متغيرات البيئة. وبهذه الطريقة، يمكن تعديل المتغيرات المستخدمة في البرنامج النصي وفقًا لحالة الاستخدام.

يجب أن يكون ملف .env في نفس المجلد الذي يوجد فيه البرنامج النصي المشغل (main.py، run.sh... إلخ)

سيؤدي ملف .env التالي إلى إنتاج متغيرات البيئة الموضحة، مما يسمح بتعديلها في تكوينات التشغيل المخصصة.

image-20250214-094006.pngimage-20260512-100857.png

متغيرات البيئة المُقدَّمة مسبقًا

يتم تمرير بعض التفاصيل المتعلقة بتشغيل البرنامج النصي إلى بيئة البرنامج النصي كمتغيرات بيئية، وهي:

  • معرف المستخدم (UserId) كـ SKOOR_USER_ID

  • اسم المستخدم كـSKOOR_USER_USERNAME

  • الاسم الكامل للمستخدم كـ SKOOR_USER_FULLNAME

توضح لقطات الشاشة أدناه كيفية استرداد هذه المتغيرات في مثال بلغة Python إلى جانب الناتج في البرنامج النصي:

import os

source_file = os.environ.get('SKOOR_SOURCE_FILE')
user_id = os.environ.get('SKOOR_USER_ID')
username = os.environ.get('SKOOR_USER_USERNAME')
userFullname = os.environ.get('SKOOR_USER_FULLNAME')
userGroup_id = os.environ.get('SKOOR_USER_USERGROUP_IDS')
userGroup_names = os.environ.get('SKOOR_USER_USERGROUP_NAMES')


print("sourceFile: ", source_file)
print("User ID: ", user_id)
print("Username: ", username)
print("Fullname: ", userFullname)
print("UserGroup ID: ", userGroup_id)
print("UserGroup name: ", userGroup_names)
image-20251201-084654.png

مثال باستخدام ملف .env

يقرأ البرنامج النصي التالي المتغير foo في ملف .env ويطبع قيمته على وحدة التحكم، وفيما يلي لقطات شاشة لملف .env وتكوينات التشغيل ذات الصلة.

image-20250214-094929.pngimage-20250214-094943.png

image-20250214-094911.png

image-20250214-095049.pngimage-20250214-095128.png

ملفات المصدر

يمكن تصميم البرامج النصية بحيث تقبل الملفات الخارجية (ملفات المصدر) وتعالجها كجزء من منطق البرنامج النصي.

يمكن الإشارة إلى الملفات المصدرية في البرنامج النصي باستخدام متغير البيئة SKOOR_SOURCE_FILE كما هو موضح في مقتطف الشفرة التالي: 

# IN PYTHON
import os

source_file = os.environ.get('SKOOR_SOURCE_FILE')
print(source_file)
#IN SHELL

echo $SKOOR_SOURCE_FILE
image-20260512-101048.png

يتم دعم أنواع الملفات التالية بشكل افتراضي، ما لم يتم تقييدها في إعدادات البرنامج النصي:

  • نص (منظم)

    • text/plain

    • text/csv

    • text/tab-separated-values

    • text/tsv

    • text/markdown

    • text/vtt

    • application/json

    • application/x-ndjson

    • application/jsonl

    • application/xml

    • text/xml

    • application/yaml

    • text/yaml

    • application/x-yaml

    • application/sql

    • text/sql

  • المستندات

    • application/pdf

    • application/msword

    • application/vnd.openxmlformats-officedocument.wordprocessingml.document

    • application/vnd.ms-excel

    • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

    • application/vnd.ms-powerpoint

    • application/vnd.openxmlformats-officedocument.presentationml.presentation

    • application/vnd.oasis.opendocument.text

    • application/vnd.oasis.opendocument.spreadsheet

    • application/vnd.oasis.opendocument.presentation

    • application/rtf

    • application/epub+zip

  • الأرشيفات

    • application/parquet

    • application/x-parquet

    • application/avro

    • application/x-avro

    • application/vnd.apache.arrow.file

    • application/vnd.apache.arrow.stream

    • application/orc

    • application/x-orc

    • application/zip

    • application/x-zip-compressed

    • application/gzip

    • application/x-gzip

    • application/x-bzip2

    • application/x-xz

    • application/zstd

    • application/x-zstd

    • application/x-tar

    • application/x-7z-compressed

تشغيل البرامج النصية الفرعية

إذا كانت البرامج النصية الفرعية مطلوبة، فيجب وضعها داخل مجلد bin. حيث إنها ستكون قابلة للتشغيل.

تأكد من وضع البرامج النصية الفرعية دائمًا في مجلد bin.

فيما يلي مثال في Shell:

image-20250423-063721.png

ناتج ملف run.sh هذا هو:

image-20250423-063801.png

image-20250423-063907.png

ناتج ملف run.sh هذا هو:

image-20250423-063955.png

QuickRun

يوفر هذا الخيار زر QuickRun الذي يقوم بتشغيل البرنامج النصي بدون ملف مصدر وباستخدام القيم الافتراضية لمتغيرات البيئة.
ويتيح تشغيل البرنامج النصي بسرعة أثناء تطويره أو استكشاف الأخطاء وإصلاحها، بينما يعرض زر Latest Job Overview (نظرة عامة على أحدث المهام) ناتج وحدة التحكم.

image-20250214-095256.png

التشغيل

بدء التشغيل

في قسم التشغيل، حدد التكوين المطلوب (وقم بتحميل ملف المصدر إذا لزم الأمر)، ثم انقر فوق «تشغيل البرنامج النصي»

image-20250214-095342.png

إلغاء التشغيل

يمكن إلغاء عمليات التشغيل الجارية وكذلك تلك التي في انتظار التشغيل بالنقر فوق رمز إلغاء المهمة في قسم "السجل".

image-20250214-095439.png

إلغاء الاشتراك في Poetry

Poetry هي أداة قوية تُستخدم لإدارة التبعيات وإدارة البيئات الافتراضية في لغة Python. ويتم ذلك من خلال تعريف ملف pyproject.toml في نفس المجلد الذي يوجد فيه البرنامج النصي للتشغيل (main.py، run.sh... إلخ).

سيؤدي إزالة ملف pyproject.toml أو إعادة تسميته إلى إلغاء استخدام Poetry تلقائيًا، واستخدام skoor-python بدلاً منه.

نظرة عامة على المهمة

لعرض التفاصيل الكاملة لأي مهمة، انقر على أحد العناصر في قائمة «السجل» كما هو موضح أدناه:

image-20250214-095601.png

image-20250214-095612.png

سجل التشغيل

يعرض قسم "السجل" قائمة بجميع عمليات تشغيل البرامج النصية. يمكن العثور على تفاصيل كل عملية تشغيل بالنقر عليها.

image-20250214-095715.png

استخدام رموز Webhook لتشغيل المحول

يتيح هذا الخيار تشغيل البرنامج النصي دون الحاجة إلى تسجيل الدخول، وهو الخيار المفضل للمستخدمين التقنيين.
لكل برنامج نصي رمز Webhook فريد، وسيتم نسخ عنوان URL إلى الحافظة بالنقر فوق Copy Webhook Token (نسخ رمز Webhook).

مثال على استخدام رموز Webhook

انسخ رمز Webhook من صفحة البرنامج النصي بالنقر فوق Copy Webhook Token (نسخ رمز Webhook)، وفي هذا المثال يبدو عنوان URL الخاص بـ Webhook كما يلي:

http://localhost:8090/scripts/8925cfd4-2063-4b07-9d56-956f2b754b47/run?token=6ae51c9f-d292-4d55-b512-4537121b37f5

استخدم عنوان URL لإرسال طلب POST:

باستخدام برنامج واجهة برمجة تطبيقات (API) مثل POSTMAN

image-20250213-145831.png

يشير الرد 200 مع كيان المهمة الأولي إلى أن التشغيل قد تم تشغيله كما هو موضح في لقطة الشاشة أدناه:

image-20250213-145952.png

استخدام cURL في المحطة الطرفية

curl -X POST http://localhost:8090/scripts/8925cfd4-2063-4b07-9d56-956f2b754b47/run?token=6ae51c9f-d292-4d55-b512-4537121b37f5

سيبدو الرد كما يلي


image-20250213-151347.png

يمكن ملاحظة هذه العملية في لوحة معلومات SKOOR، وتظهر العملية التي أنشأها مستخدم الرمز المميز في السجل.

image-20250214-095924.png

image-20250214-095945.png

الحذف

انقر على زر قائمة السياق واختر رمز سلة المهملات لحذف البرنامج النصي. سيظهر زر قائمة السياق عند تمرير مؤشر الماوس فوق اسم البرنامج النصي.

image-20260731-130723.png

تصدير البرنامج النصي (البرامج النصية) كملف Zip

انقر على زر قائمة السياق واختر زر التصدير لتصدير نص برمجي واحد. سيظهر الرمز عند تمرير مؤشر الماوس فوق اسم النص البرمجي.
يمكنك أيضًا تصدير مجموعة كاملة أو حتى جميع النصوص البرمجية المتوفرة على النظام.

يتم تضمين ملف script_metadata.json داخل ملف ZIP المُصدَّر، ويحتوي على الوصف، ووقت الانتظار الافتراضي، وتكوين التشغيل، وتكوين الجدول الزمني للنص البرمجي.

في متصفح Safari: قم بتعطيل الإعدادات → عام → «فتح الملفات "الآمنة" بعد التنزيل» لمنع الاستخراج التلقائي لملفات ZIP.

image-20260731-130907.png

السابق
استعلامات StableNet
التالي
دليل الترحيل إلى البرامج النصية في سكور-8.1