كتابة ملف إلى التخزين من داخل سكربت

الهدف

اجعل واجهة برمجية مخصّصة تبني ملفًا — تصدير CSV، أو ملف JSON لنظام آخر — وتضعه حيث يستطيع نظام خارجي أن يلتقطه.

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

للمنصّة ثلاثة أماكن يعيش فيها الملف، وهي ليست بدائل بعضها لبعض.

	لأجل	مثال
موارد الويب	ملفات هي جزء من التطبيق نفسه	شعار، ورقة أنماط
ملفات السجل	ملف يخصّ سجلًا واحدًا	صورة جهة اتصال، عقد موقّع
تخزين الكائنات	ملفات لا تخصّ أي سجل	تصدير شهري، ملف تُسقطه تكاملة

ملف السجل ملتصق بسجله ويسافر معه. أما التصدير فلا يخصّ سجل أحد — لا يوجد صف يعلّق عليه — وهذا بالضبط ما وُجد تخزين الكائنات لأجله.

قبل أن تبدأ

تحتاج إلى اسم دلو. لست بحاجة إلى إنشائه: أول كتابة تنشئه.

أسماء الدلاء حروف لاتينية صغيرة وأرقام وشرطات، من ٣ إلى ٦٣ محرفًا. وهي مشتركة بين كل المستأجرين، كما هي في S3، فاسم بسيط مثل exports قد يكون مأخوذًا — ضع قبله بادئة من عندك، كما في par-exports أدناه.

ما يستطيع السكربت فعله


`putFile(bucket, key, text)`	يكتب ملفًا. يجيب `true`، أو `false` إن لم يستطع
`putFileAs(bucket, key, text, contentType)`	المثل، مع قول أي نوع من الملفات هو
`getFile(bucket, key)`	يقرؤه نصًّا — والسلسلة الفارغة إن لم يكن موجودًا
`fileExists(bucket, key)`	`true` أو `false`
`listFiles(bucket, prefix)`	الملفات تحت بادئة، لكلٍّ `key` و`size` و`contentType` و`uploadedAt`
`deleteFile(bucket, key)`	يزيل واحدًا

المفتاح هو مسار الملف داخل الدلو — claims/2026-09.csv. والشرطات المائلة فيه جزء من الاسم لا أكثر، لكنها تُقرأ كمجلدات في شاشة التخزين، فالتجميع بها يستحق العناء.

الخطوات

١. افتح حلّك واختر الواجهات المخصّصة، ثم جديد. ٢. أعطها مسارًا — claims/export/{period} — واختر Post. ٣. في السكربت، ابنِ الملف نصًّا واكتبه:

var claims = runQuery({ entity: 'par_claim', select: ['par_name', 'par_amount'] });

var csv: string = 'reference,amount\n';
for (var i: int = 0; i < claims.length(); i++) {
  csv = csv + `${claims[i].par_name},${claims[i].par_amount}` + '\n';
}

putFileAs('par-exports', 'claims/' + getInput('period') + '.csv', csv, 'text/csv');

٤. احفظ، ثم استدعها.

ثلاثة أمور تُوقع الناس

length() يحتاج قوسيه. claims.length ليس خطأ — بل لا شيء، فالحلقة المحروسة به لا تعمل أبدًا ويخرج تصديرك سطرَ عناوين لا غير. وهذا هو الخطأ الوحيد هنا الذي لا يُعلن عن نفسه.
لا تستطيع جمع رقم مع نص. 'Total: ' + amount مرفوض. ضع الرقم في قالب الشرطة الخلفية بدلًا من ذلك — `Total: ${amount}` — وهو الطريق الوحيد لتحويله إلى نص.
قل أي نوع من الملفات هو. putFile يخزّنه نصًّا عاديًا، والمتصفّح يعرض النص العادي في التبويب بدل حفظه. استخدم putFileAs مع text/csv أو application/json أو ما هو عليه حقًّا.

تأكّد أنه نجح

اذهب إلى الإدارة ← التخزين، افتح الدلو، وستجد الملف بحجمه ونوعه. نزّله وتحقّق من محتواه.

ما ليس هذا لأجله

الملفات الثنائية الكبيرة. ملف السكربت نصّ بناه بنفسه. أما الصور وملفات PDF والأرشيفات فتتولّاها المنصّة نفسها، وهي تبثّها بثًّا.
ملف يخصّ سجلًا. ضع عمود ملف أو صورة على الجدول بدلًا من ذلك — يُقدَّم تحت صلاحيات السجل نفسه، وحذف السجل يأخذ الملف معه.
إعطاء أحدهم رابطًا. هذه الدوال تسلّم سكربتك النصّ؛ ولا تسكّ عنوانًا. والرابط الذي يعمل دون تسجيل دخول مفتاح يستطيع أي أحد تمريره، فهو خطوة مقصودة في مكان آخر لا شيء يفعله سكربت عرضًا.

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

«لم يُعثر على الدلو.» أنت تقرأ أو تسرد دلوًا لم يوجد بعد — الكتابة وحدها هي التي تنشئ دلوًا. اكتب أولًا، أو تحقّق من الإملاء.

لا شيء في الملف سوى العناوين. length بلا قوسين. انظر أعلاه.

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

«هذا التشغيل بلا مستدعٍ.» السكربت خطوة إضافة غير متزامنة. تلك تعمل بعد انتهاء الطلب الذي أدرجها، فلا أحد يُتصرَّف باسمه. استخدم خطوة متزامنة، أو واجهة مخصّصة.

انظر أيضًا

نشر واجهة مخصّصة
حلّ العيّنة custom-api-object-storage-export، وهو هذه الصفحة في صورة شيء يمكنك استيراده وتشغيله.

الهدف​

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

قبل أن تبدأ​

ما يستطيع السكربت فعله​

الخطوات​

ثلاثة أمور تُوقع الناس​

تأكّد أنه نجح​

ما ليس هذا لأجله​

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

انظر أيضًا​