تشغيل دالة

الهدف

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

لماذا يوجد هذا

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

الدالة سكربت بلغة BS تشغّله خدمة الدوال بنفسها، في عمليتها الخاصة، وللمدة التي تسمح بها. وهي مكوّن من مكوّنات حلك، مثل النموذج أو السكربت، فتُكتب في Dev وتنتقل إلى Test وProduction ضمن حزمة الحل.

قبل أن تبدأ

• حل له ناشر.
• الجداول التي ستقرأ منها دالتك وتكتب فيها.
• إن كانت تستدعي خدمة خارجية أو ترسل بريدًا، فمتغير البيئة الذي يسمّيها — راجع استدعاء خدمة خارجية من سكربت.

الخطوات

1. افتح حلك واختر الدوال في الشريط الجانبي، ثم جديد.
2. في تبويب السكربت اكتب ما تفعله الدالة. يمكنها قراءة السجلات وكتابتها، وقراءة الملفات وكتابتها، واستدعاء خدمات خارجية، وimport لسكربتات الحل — أي ما تستطيعه خطوة الإضافة. تعرض العين في نهاية شريط التبويبات كل دالة يمكنك استدعاؤها.
3. في تبويب الإعدادات امنحها اسم عرض. يُملأ الاسم المنطقي تلقائيًا.
4. قرّر متى تعمل. يمكن تشغيل أي دالة يدويًا. ولتعمل من تلقاء نفسها أيضًا، فعّل تعمل وفق جدول واختر فاصلًا — كل ١٥ دقيقة، كل ٦ ساعات، كل يوم. وللجدول اليومي يمكنك تحديد الساعة والمنطقة الزمنية.
5. حدّد أقصى مدة تشغيل — المدة التي يُسمح للتشغيل بالاستمرار فيها قبل إيقافه. الافتراضي ١٥ دقيقة ويمكن أن تصل إلى يوم.
6. اختر حفظ. السكربت الذي لا يُحلَّل يُرفَض الآن، مع رقم السطر الذي يفشل فيه.
7. اختر تشغيل الآن. يُفتح تبويب التشغيلات ويتابع التشغيل: في الطابور، ثم قيد التشغيل، ثم كيف انتهى. اختر التشغيل لقراءة سجله.

كتابة سجل

لا أحد يراقب الدالة وهي تعمل، لذا سجلها هو طريقتك لمعرفة ما فعلته.

var due = queryRecords('par_membership', 'par_reminder_state', 'due');
log('Reminders due: ' + toJson(due.length()));

for (var i: int = 0; i < due.length(); i++) {
  updateRecord('par_membership', due[i].id, { par_reminder_state: 'sent' });
  log(due[i]);
}

• يُكتب النص كما هو، والرقم كما تكتبه، والسجل أو القائمة بصيغة JSON — فيعرض log(due[i]) السجل كاملًا كما رآه التشغيل.
• يعرض تبويب التشغيلات الأسطر والتشغيل ما زال جاريًا، بتأخير ثوانٍ قليلة.
• يحتفظ التشغيل الواحد بـ٥٠٠٠ سطر على الأكثر، وآخر سطر محفوظ يقول إن السجل امتلأ.
• يوقف الاحتفاظ بأسطر السجل في تبويب الإعدادات التسجيل. يظل log يعمل ولا يحتفظ بشيء، فلا تحتاج أبدًا إلى تعديل السكربت لإسكاته — أو لإعادة تشغيله.

إنهاء التشغيل عمدًا

ينهي stop('reason') التشغيل في مكانه، نجاحًا يذكر السبب:

if (due.length() == 0) {
  stop('Nobody is due a reminder tonight.');
}

تعرض نتيجة التشغيل هذه الجملة. هذا مختلف عن الفشل، وقائمة التشغيلات تعرضه كذلك.

بدء دالة من نص برمجي

لا تحتاج الدالة إلى ساعة. يمكن لـ Custom API أو plugin step أو دالة أخرى أن تبدأها بـ startFunction، وتمنحها مُدخلات، وتستعيد معرّف التشغيل فورًا — فالعمل يجري بعد ذلك في خدمة Functions. هكذا يُجاب طلب يحتاج إلى ساعة من العمل في لحظة.

// A Custom API: POST reports  { "period": "2026-10" }
var run = startFunction('par_sales_report', { period: getInput('period') });
setStatus(202);
setOutput('run', run);

// The function
var asked = functionInput();
// … the long work …
setResult({ period: asked.period, total: total });

// A second Custom API: GET reports/runs/{run}
var run = functionRun(getInput('run'));
if (run == null) { setStatus(404); } else { setOutput('status', run.status); setOutput('report', run.result); }

• تُرجع startFunction(name, input) معرّف التشغيل. المدخلات — سجل أو قائمة أو قيمة أو null — هي ما تقرؤه الدالة بـ functionInput(). التشغيل الذي بدأه الجدول الزمني أو Run now لا مدخلات له، ويقرأ null.
• setResult(value) هو ما يعيده التشغيل. تُحفظ القيمة الأخيرة فقط، وفقط إذا نجح التشغيل. اجعلها صغيرة — ملخصًا أو مفتاح ملف — لأنها تُقرأ في كل مرة يسأل فيها أحد عن حال التشغيل.
• تُرجع functionRun(id) القيمة { id, function, status, outcome, result, queuedAt, startedAt, finishedAt }، أو null إن لم يوجد مثل هذا التشغيل.
• من plugin step، يبدأ التشغيل داخل عملية الكتابة نفسها: إذا رُفضت الكتابة، لا يبدأ التشغيل أبدًا.
• عمليات التشغيل التي يبدؤها نص برمجي غير مقيّدة بقاعدة «واحد في كل مرة». شخصان يطلبان في الوقت نفسه يحصلان على تشغيلين. قاعدة الواحد في كل مرة هي للجدول الزمني و Run now.
• في علامة التبويب Runs، يظهر مثل هذا التشغيل بـ كيف بدأ: نص برمجي، وعند تحديده تظهر المدخلات و النتيجة فوق السجل.
• إذا لم تكن الدالة موجودة أو كانت متوقفة، توقف startFunction النص البرمجي مع السبب، فلا يُقال للمستدعي أبدًا إن عملًا بدأ وهو لم يبدأ.

أن تُبلَّغ عند انتهاء التشغيل

يمكن للمستدعي الذي لا يريد أن يظل يسأل أن يُبلَّغ. startFunctionWithCallback هي startFunction مع وسيط إضافي واحد: اسم متغير بيئة يحمل العنوان المطلوب إبلاغه. عندما ينتهي التشغيل — أيًّا كانت طريقة انتهائه — تُرسل نتيجته إليه مرة واحدة.

// A Custom API: POST totals
var run = startFunctionWithCallback('par_invoice_totals', null, 'par_totals_done');
setStatus(202);
setOutput('run', run);

ما يصل:

{ "run": "…", "function": "par_invoice_totals", "status": "Succeeded",
  "outcome": null, "result": { "invoices": 3, "total": 165.5 }, "finishedAt": "…" }

• لا عنوان URL في البرنامج النصي أبدًا. الوسيط الثالث اسم متغير بيئة، كما في callService؛ ويقرر المسؤول إلى أين يشير في كل بيئة. الاسم الذي لا يعلنه الحل يوقف البرنامج النصي قبل أن يبدأ أي شيء.
• يُرسل مرة واحدة ولا يُعاد. في علامة التبويب التشغيلات، يُظهر تحديد التشغيل الإشعار عند الانتهاء وما آل إليه — Delivered (HTTP 200)، أو الحالة التي أجابت بها الخدمة، أو سبب تعذّر استدعائها. ويظل بإمكان المستدعي الذي فاته الإشعار قراءة التشغيل بـ functionRun.
• حالة التشغيل نفسه لا تعتمد عليه. التشغيل الذي أنجز عمله ينجح حتى لو كانت الخدمة التي كان يجب إبلاغها متوقفة.

كتابة ملف

يمكن للدالة أن تكتب في تخزين الكائنات بالاستدعاءات نفسها التي يستخدمها Custom API — putFile وputFileAs وgetFile وlistFiles وdeleteFile — مع أنه لا أحد مسجّل الدخول عند تشغيلها.

var key = 'orders/' + today() + '.csv';
putFileAs('par-order-exports', key, csv, 'text/csv');
setResult({ bucket: 'par-order-exports', key: key, rows: orders.length() });

• يذهب الملف إلى تخزين مؤسستك ويُحتسب من حصة التخزين الخاصة بها. الكتابة التي تتجاوز الحصة تُفشل التشغيل.
• في الإدارة ← التخزين يظهر أن الملف رفعه function:<name> — الدالة هي التي كتبته، لا من ضغط تشغيل الآن.
• هكذا تُعيد الدالة أكثر من ملخّص: اكتب البيانات في ملف وضع مفتاح الملف في النتيجة.
• لا شيء يحذف الملفات القديمة نيابةً عنك. الدالة التي تكتب ملفًا كل ليلة ينبغي أن تحذف ما لم تعد تحتاجه، كما يفعل النموذج functions-nightly-export-to-storage.

كيف ينتهي التشغيل

الحالة	ما حدث
نجح	انتهى السكربت، أو أوقف نفسه بـstop(...)
فشل	أخطأ السكربت، أو رُفضت عملية كتابة قام بها، أو تجاوز أقصى مدة تشغيل، أو توقفت الخدمة أثناء التشغيل. النتيجة تقول أيّها
أُلغي	ضغط أحدهم إلغاء التشغيل

لا يُعاد التشغيل الفاشل نيابةً عنك أبدًا. قد تعمل الدالة طويلًا، وتكرار تسع وعشرين دقيقة من العمل دون علمك أسوأ من التوقف. اقرأ سبب الفشل، وأصلح ما يلزم، ثم اضغط تشغيل الآن.

تأكد من نجاحه

• التشغيل نجح، وسجله يقول ما توقعته.
• افتح سجلًا غيّرته الدالة وانظر إلى سجل التدقيق: التغيير مسجَّل باسم الدالة لا باسم شخص. الدالة تعمل بصفتها المنصة، دون أحد خلفها.
• للدالة المجدولة، التشغيل التالي في تبويب الإعدادات هو موعد تشغيلها التالي من تلقاء نفسها.

أمور ينبغي معرفتها

• تشغيل واحد في كل مرة. ما دام هناك تشغيل في الطابور أو قيد التشغيل يُرفض «تشغيل الآن»، ويُتخطّى الجدول الذي يحين موعده حتى المرة التالية. فالتشغيل الليلي الذي طال لا يبدأ مرتين على السجلات نفسها.
• «تشغيل الآن» يشغّل النسخة المحفوظة ولا يُتاح والصفحة فيها تغييرات غير محفوظة.
• الموقوفة موقوفة. الدالة الموقوفة لا تعمل وفق جدولها ولا يدويًا.
• تغيير السكربت لا يحرّك الجدول؛ تغيير الجدول يحرّكه.
• إلغاء التشغيل يوقف السكربت خلال ثوانٍ — حتى حلقة لا تلمس أي سجل.
• تحتفظ كل دالة بآخر ٢٠٠ تشغيل.

استكشاف الأخطاء

العَرَض	السبب المحتمل	الحل
تشغيل الآن معطّل	تغييرات غير محفوظة، أو الدالة موقوفة	احفظ؛ فعّلها
هذه الدالة قيد التشغيل بالفعل	تشغيل في الطابور أو جارٍ	انتظره، أو اختره ثم إلغاء التشغيل
فشل التشغيل: Stopped after … minutes	تجاوز أقصى مدة تشغيل	ارفع أقصى مدة تشغيل، أو اجعل كل تشغيل يعمل أقل
فشل التشغيل لأن الخدمة توقفت أثناءه	أُعيد تشغيل الخدمة أثناء التشغيل	شغّلها مرة أخرى
السجل فارغ	الاحتفاظ بأسطر السجل موقوف، أو لا يستدعي السكربت log	فعّله؛ أضف log(...)
فشل التشغيل: There is not enough storage left	نفدت حصة التخزين الخاصة بالمؤسسة	احذف الملفات التي لم تعد تحتاجها، أو رقِّ الخطة
فشل التشغيل: Object storage is not configured for the Functions service	لم يمنح النشرُ خدمةَ الدوال إعدادات التخزين	اسأل المسؤول

انظر أيضًا

• استدعاء خدمة خارجية من سكربت
• كتابة سكربت حل
• نشر واجهة API مخصصة