حذف الملفات باستخدام API Token

حذف الملفات عبر API Token مخصص للسكربتات، ومهام الأتمتة، وبرامج الجهات الخارجية. لا تحتاج إلى فتح صفحة الإدارة. ما دمت توفّر عنوان الموقع، والرمز، ومعرّفات ملفات صريحة، يمكنك حذف ملف واحد أو عدة ملفات من ImgHost.

الحذف عملية كتابة، وهو يحذف البيانات فعليًا بعد تشغيل الأمر. استخدم imghost-token-list.mjs أولًا لتأكيد قيم fileId التي تريد حذفها، ثم مرّر هذه المعرّفات إلى سكربت الحذف.

قبل البدء

افتح لوحة الإدارة، ثم انتقل إلى:

System Settings -> Security Settings -> API Token

عند إنشاء API Token أو تعديله، تأكد من أن الرمز يسمح بالحذف. لا يحتاج هذا السكربت إلا إلى صلاحية delete.

يمكنك أيضًا وضع الرمز في متغير بيئة:

$env:IMGHOST_API_TOKEN="your API Token"

تنزيل السكربت

السكربت	الغرض
سكربت حذف الملفات	حذف معرّف ملف واحد أو عدة معرّفات ملفات محددة صراحة.

يتطلب ذلك Node.js 18 أو إصدارًا أحدث.

سلوك واجهة الحذف

يستدعي سكربت الحذف واجهة الحذف الخلفية:

POST /api/manage/delete/batch

يجب أن يتضمن الطلب API Token:

Authorization: Bearer <token>

مثال على جسم الطلب:

{
  "fileIds": ["photos/2026/a.txt"],
  "deleteStrictness": "strict"
}

إذا كانت fileIds تحتوي على ملف واحد، فهذه عملية حذف ملف واحد. وإذا كانت تحتوي على عدة ملفات، فهذه عملية حذف دفعي. يعالج الخادم الخلفي 15 ملفًا كحد أقصى في الطلب الواحد، ويقسّم السكربت العمل تلقائيًا إلى عدة طلبات وفق --batch-size.

تعيد الواجهة تدفق تقدّم بصيغة NDJSON. تشمل الأحداث الشائعة batch_start وfile_step وfile_done وbatch_complete وbatch_error. يحلل السكربت هذه الأحداث ويلخصها كمخرجات قابلة للقراءة أو كمخرجات JSON.

بعد نجاح الحذف، يتولى الخادم الخلفي تلقائيًا معالجة فهارس الملفات، وإحصاءات المجلدات، وإحصاءات السعة، ومسح ذاكرة التخزين المؤقت.

معلمات سكربت الحذف

المعلمة	إلزامية	الوصف
--base-url <url>	نعم	عنوان موقع ImgHost، مثل https://image.ai6.me.
--token <token>	نعم	API Token. يمكنك أيضًا استخدام متغير البيئة IMGHOST_API_TOKEN.
--file-id <id>	نعم	معرّف الملف المراد حذفه. يمكنك تمريره أكثر من مرة.
--strictness <strict|soft>	لا	صرامة الحذف. القيمة الافتراضية strict.
--batch-size <n>	لا	عدد الملفات في كل طلب. القيمة الافتراضية 15، والحد الأقصى 15.
--retries <n>	لا	عدد إعادة المحاولة عند الفشل المؤقت. القيمة الافتراضية 3.
--timeout-ms <n>	لا	مهلة كل طلب. القيمة الافتراضية 180000.
--output <pretty|json>	لا	صيغة الإخراج. القيمة الافتراضية pretty.
--save-response <path>	لا	حفظ النتيجة النهائية كملف JSON.
-h / --help	لا	عرض مساعدة السكربت.

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

الحذف الصارم والحذف المرن

الوضع	الوصف
strict	الوضع الافتراضي. إذا فشل الحذف من التخزين البعيد، يبقى سجل ImgHost حتى تتمكن من إعادة المحاولة أو التحقيق.
soft	إذا فشل الحذف من التخزين البعيد، يستمر تنظيف سجل ImgHost، وتعيد النتيجة تحذيرًا.

إذا كان حذف الملف البعيد شرطًا لاعتبار الأمر ناجحًا، فاستخدم الوضع الافتراضي strict. وإذا لم تعد المنصة البعيدة قادرة على حذف الكائن وتريد فقط تنظيف سجل ImgHost، فاستخدم soft.

أمثلة

حذف ملف واحد:

node imghost-token-delete.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --file-id "photos/2026/a.txt"

استخدام الرمز من متغير البيئة:

$env:IMGHOST_API_TOKEN="your API Token"

node imghost-token-delete.mjs `
  --base-url "https://your-domain" `
  --file-id "photos/2026/a.txt"

حذف عدة ملفات:

node imghost-token-delete.mjs `
  --base-url "https://your-domain" `
  --file-id "photos/2026/a.txt" `
  --file-id "photos/2026/b.txt" `
  --file-id "photos/2026/c.txt"

تنظيف سجل ImgHost حتى عند فشل الحذف من التخزين البعيد:

node imghost-token-delete.mjs `
  --base-url "https://your-domain" `
  --file-id "photos/2026/a.txt" `
  --strictness soft

إخراج JSON وحفظ النتيجة:

node imghost-token-delete.mjs `
  --base-url "https://your-domain" `
  --file-id "photos/2026/a.txt" `
  --output json `
  --save-response ".\delete-result.json"

تقييد كل طلب إلى 5 ملفات:

node imghost-token-delete.mjs `
  --base-url "https://your-domain" `
  --file-id "photos/2026/a.txt" `
  --file-id "photos/2026/b.txt" `
  --batch-size 5

التحقق من fileId قبل الحذف

يحتاج سكربت الحذف إلى معرّفات ملفات ImgHost. يمكنك استخدام سكربت العرض أولًا لفحص الملفات داخل مجلد:

node imghost-token-list.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --files `
  --dir "photos/2026" `
  --count 10 `
  --output json

عادةً ما يكون الحقل name في النتيجة هو fileId الذي يمكنك تمريره إلى سكربت الحذف.

الأسئلة الشائعة

لماذا فشل الحذف لكن الملف ما زال في القائمة؟

عند استخدام الوضع الافتراضي strict، يبقى سجل ImgHost إذا فشل الحذف من التخزين البعيد. يمنع ذلك حذف الفهرس المحلي فقط بينما يبقى الملف البعيد موجودًا. بعد التأكد من أنك تريد تنظيف سجل ImgHost فقط، أعد المحاولة على fileId نفسه باستخدام soft.

لماذا تظهر تحذيرات في النتيجة؟

تعني التحذيرات عادةً وجود مشكلة غير قاتلة أثناء الحذف من التخزين البعيد، أو مسح ذاكرة التخزين المؤقت، أو إنهاء الإحصاءات. يلخص السكربت التحذيرات حتى تتمكن من تحديد ما إذا كانت إعادة المحاولة ضرورية.

هل يمكنني حذف مجلد كامل دفعة واحدة؟

لا يوفر هذا السكربت عملية إفراغ مجلد. استخدم سكربت العرض أولًا لتصفية قيم fileId الصريحة، ثم مرّر الملفات التي تريد حذفها واحدًا تلو الآخر.