حذف فایل با API Token

حذف فایل با API Token برای اسکریپت‌ها، کارهای خودکار و برنامه‌های بیرونی مناسب است. نیازی نیست پنل مدیریت را باز کنید؛ کافی است نشانی سایت، API Token و شناسه‌های دقیق فایل را بدهید تا یک یا چند فایل از ImgHost حذف شوند.

حذف یک عملیات نوشتنی است و پس از اجرای فرمان، داده‌ها واقعاً حذف می‌شوند. بهتر است ابتدا با imghost-token-list.mjs مقدارهای fileId مورد نظر را بررسی کنید و سپس همان شناسه‌ها را به اسکریپت حذف بدهید.

آماده‌سازی

در پنل مدیریت باز کنید:

System Settings -> Security Settings -> API Token

هنگام ساخت یا ویرایش API Token، مطمئن شوید مجوز حذف فعال است. این اسکریپت فقط به مجوز delete نیاز دارد.

API Token را می‌توان در متغیر محیطی هم قرار داد:

$env:IMGHOST_API_TOKEN="your API Token"

دانلود اسکریپت

اسکریپت	کاربرد
اسکریپت حذف فایل	حذف یک یا چند شناسه فایل که صریحاً مشخص شده‌اند

برای اجرا، Node.js 18 یا نسخه جدیدتر لازم است.

رفتار API حذف

اسکریپت حذف، رابط حذف در سمت سرور را فراخوانی می‌کند:

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"

استفاده از API Token در متغیر محیطی:

$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 را فیلتر کنید و سپس فایل‌هایی را که می‌خواهید حذف شوند، یکی‌یکی به اسکریپت حذف بدهید.