ساخت پوشه و آپلود فایل - REST

نکته: در صورتی که با مفهوم REST و سرویس‌های سمت سرور و یا با دستور curl آشنایی ندارید، به آشنایی با REST مراجعه کنید.

پیش‌نیازها

  1. در صورتی که با سرویس فایل آشنایی ندارید، به معرفی سرویس فایل مراجعه کنید.
  2. در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای سرویس فایل خود را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
  3. در صورتی که با درخواست Multipart آشنایی ندارید، به درخواست Multipart مراجعه کنید.
  4. در صورتی که با راه‌اندازی کتابخانه REST در پلتفرم خود آشنایی ندارید، به راه‌اندازی کتابخانه‌های REST مراجعه کنید.
  5. در صورتی که با سرویس کاربران بکتوری آشنایی ندارید، به معرفی سرویس کاربران مراجعه کنید.

این مستند به شما کمک خواهد کرد تا از طریق سرویس‌های REST ساده‌ترین اعمال سرویس فایل را انجام دهید. پایه‌ای ترین اعمالی که باید بتوانید انجام دهید، شامل آپلود یک فایل به یک پوشه دلخواه و ساخت پوشه‌های دلخواه می‌باشد.

توجه: در همه درخواست‌ها مقدار هدر X-Backtory-Storage-Id باید از صفحه پروژه، بخش کلیدها استخراج و دریافت شود.

آپلود یک فایل

جهت قرار دادن یک فایل بر روی سرویس فایل، می‌توانید از این سرویس استفاده کنید. دقت کنید که درخواست آپلود از نوع Multipart است و درخواست عادی نیست. در صورتی که با این مفهوم آشنایی ندارید، به درخواست Multipart مراجعه کنید.

به کمک این سرویس شما می‌توانید چندین فایل را در یک درخواست آپلود کنید. نمونه‌ای از درخواست آپلود به این صورت است:

curl -X POST \
    --header "Authorization: Bearer 48378438…" \
    --header "X-Backtory-Storage-Id: 125653265" \
    --form fileItems[0].fileToUpload=@"/path/to/file1.txt"  \
    --form fileItems[0].path="/path1/path2/"    \
    --form fileItems[0].replacing=true  \
    --form fileItems[1].fileToUpload=@"/path/to/file2.txt"  \
    --form fileItems[1].path="/path1/path3/"    \
    --form fileItems[1].replacing=true  \
    http://storage.backtory.com/files

در درخواست بالا فیلدها به شرح زیر اند:

نکته: در صورتی که پوشه‌های درخواست شده وجود نداشته باشد، سرویس آپلود به صورت پیشفرض این پوشه‌ها را خواهد ساخت.

سرویس فایل در پاسخ یک json حاوی یک لیست از Urlها بازخواهد گرداند که آدرس نهایی فایل‌های آپلود شده است. برای مثال پاسخ درخواست بالا مشابه شکل زیر است:

{
  "savedFilesUrls" : ["path1/path2/file1.txt", "path1/path3/file2.txt"]
}

پاسخ بالا بدین معنی است که آدرس نهایی فایل شما برابر است با:

http://storage.backtory.com/<bucket-name>/path1/path2/file1.txt
http://storage.backtory.com/<bucket-name>/path1/path3/file2.txt

که bucket-name نام مخزن شماست که توسط کلید X-Backtory-Storage-Id به طور یکتا تعیین می‌شود. در این مثال ساده پاسخ بکتوری مشابه با درخواست شما و آدرسی‌است که خواسته‌اید. در صورتی که در نام فایل‌ها کاراکترهای ویژه، کاراکتر فاصله و یا حروف فارسی و … باشد، پاسخ سرویس بکتوری کاملا متفاوت خواهد بود. برای مثال اگر نام فایل شما به جای file1.txt برابر با file 1 .txt بود (یعنی دو کاراکتر فاصله قبل و بعد از عدد ۱ وجود داشت) پاسخ بکتوری چیزی شبیه این می‌شد:

{
  "savedFilesUrls" : ["path1/path2/file%201%20.txt", "path1/path3/file2.txt"]
}

همانطور که می‌بینید مقدار فایل اول تغییر کرده و کاراکترهای نامتعارفی که معادل با کاراکتر فاصله است آمده است. در این صورت آدرس فایل شما برابر خواهد بود با

http://storage.backtory.com/<bucket-name>/path1/path2/file%201%20.txt
http://storage.backtory.com/<bucket-name>/path1/path3/file2.txt

بنابر این همیشه باید پاسخ آپلود را معیار برای تعیین Url فایل آپلود شده قرار دهید و نه فیلدهایی که در درخواست خود ارسال کرده‌اید.

پاسخ‌هایی که ممکن است از سرویس بکتوری دریافت کنید به صورت جدول زیر است:

Tables Description
200-OK Successfully uploaded
400-Bad Request Your request syntax is not correct
417-Expectation Failed One of the uploaded files already exists
500-Internal Server Error Backtory server failed to respond

دسترسی امن (Https)

تمامی سرویس‌های بکتوری دارای نسخه امن نیز هستند و کافیست در همه Urlها به جای http از Https استفاده کنید.

برای مثال آدرس فایل‌ها در درخواست آپلود در بخش قبل به صورت زیر خواهد شد:

https://storage.backtory.com/<bucket-name>/path1/path2/file%201%20.txt
https://storage.backtory.com/<bucket-name>/path1/path3/file2.txt

درخواست آپلود، ساخت پوشه و … هم به همین صورت می‌تواند بر بستر https باشد.

ساخت پوشه

در صورتی که قصد دارید در بکتوری پوشه تهی (بدون فایل) بسازید بایستی از این سرویس استفاده کنید. این عمل معادل New folder در سیستم‌عامل ویندوز یا لینوکس است. برای این کار کافیست درخواستی مشابه زیر را ارسال کنید:

curl -X POST \
    --header "Authorization: Bearer 42767…" \
    --header "X-Backtory-Storage-Id: 125653265" \ 	
    --header "Content-Type: application/json" \
    -d \
    '{
        "path" : "/path1/path2/"
     }' \
    http://storage.backtory.com/directories

سرویس فایل در پاسخ با یکی از کدهای http زیر نتیجه عملیات را اطلاع‌رسانی خواهد کرد:

Tables Description
200-OK Directory already exists, storage is OK to it
201-Created Successfully created
400-Bad Request Syntax issue in request
401-Unauthorized Unauthorized access
404-Not Found Wrong X-Backtory-Storage-Id
500-Internal Server Error Backtory server failed to respond

همانطور که دیده می‌شود، این سرویس در صورتی که پوشه قبلا وجود داشته باشد کد ۲۰۰ و در صورت عدم وجود کد ۲۰۱ باز خواهد گرداند که هر دو کد موفقیت هستند.

گام بعدی