پشتیبان‌گیری و فنی
API آپلود فایل چیست و چطور از آن استفاده کنیم؟
به‌روزرسانی:
پاسخ کوتاه
API آپلود فایل رابطی است که برنامه یا سایت شما با آن، بدون دخالت کاربر، فایل را به یک فضای ذخیره‌سازی می‌فرستد. در API پوشه آپلود ساده سه مرحله دارد: درخواست آپلود (بررسی نام، حجم و سهمیه)، ارسال محتوای فایل، و تأیید نهایی که بررسی ویروس و پردازش را شروع می‌کند. برای فایل‌های بزرگ‌تر یا اینترنت ناپایدار، آپلود چندتکه قابل ادامه وجود دارد.
آپلود ساده یا چندتکه؟
| آپلود ساده | آپلود چندتکه (upload session) | |
|---|---|---|
| مراحل | POST /uploads ← PUT محتوا ← POST finalize | POST /upload-sessions ← PUT هر تکه ← POST complete |
| قطع اتصال | باید از اول فرستاد | فقط تکه‌های باقی‌مانده فرستاده می‌شوند |
| تکه‌ها | — | به هر ترتیب و موازی؛ قابل ارسال دوباره |
| مناسب برای | فایل‌های کوچک و اتصال پایدار | فایل‌های بزرگ‌تر و اینترنت ناپایدار |
گام‌به‌گام با API پوشه
- در تنظیمات فضای کاری یک کلید API با کمترین دسترسی لازم بسازید؛ کلید فقط یک بار نمایش داده می‌شود.
- هر درخواست سرآیند Authorization: Bearer و کلید را دارد. کلید را در کد یا مخزن نگذارید؛ در متغیر محیطی نگه دارید.
- POST /uploads با نام و حجم فایل؛ پاسخ شناسه نسخه (versionId) است.
- PUT /uploads/{versionId}/content با بدنه application/octet-stream و Content-Length.
- POST /uploads/{versionId}/finalize؛ فایل بررسی ویروس و پردازش می‌شود.
- برای POSTها سرآیند Idempotency-Key بفرستید تا اگر اتصال قطع شد، تکرار درخواست کار را دو بار انجام ندهد.
نمونه‌ها و SDK
نمونه کامل با curl، جاوااسکریپت (SDK رسمی با مجوز MIT)، پایتون و PHP، فهرست دسترسی‌ها، خطاها و صفحه‌بندی در بخش توسعه‌دهندگان آمده است.
محدودیت‌ها را بدانید
- سقف حجم هر فایل و سهمیه فضا مثل پنل به پلن بستگی دارد.
- فایل‌های اجرایی و محتوای فعال وب پذیرفته نمی‌شوند.
- دسترسی کلید هرگز بیشتر از نقش فعلی عضوی که آن را ساخته نیست.
پرسش‌های متداول
- میتوانم از مرورگر کاربر مستقیم آپلود کنم؟
- کلید API را هرگز در کد سمت مرورگر نگذارید. آپلود را از سرور خودتان انجام دهید، یا برای گرفتن فایل از دیگران «درخواست فایل» بسازید.
- بعد از آپلود چطور بفهمم پردازش تمام شد؟
- وضعیت سند را بخوانید یا وبهوک تعریف کنید تا رویدادهای مربوط برای سرور شما فرستاده شود.