مدیریت فایل‌ها و پوشه‌ها - REST

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

پیش‌نیازها

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

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

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

به‌دست آوردن اطلاعات یک پوشه

در صورتی که قصد خواندن اطلاعات فایل‌ها و زیرپوشه‌های یک پوشه را دارید، بایستی از این سرویس استفاده کنید. در اصطلاح به خواندن این اطلاعات Directory Listing گفته می‌شود. با توجه به اینکه تعداد زیر فایل‌ها و پوشه‌های مستقیم یک پوشه ممکن است بسیار زیاد باشد، شما قادر به دریافت همه آنها در یک درخواست ندارید و حداکثر ۵۰ رکورد را می‌توانید در یک درخواست بازیابی کنید. به همین دلیل این سرویس به صورت صفحه صفحه اطلاعات را در اختیار شما قرار می‌دهد.

توجه:‌ این سرویس از طریق اپ موبایل قابل دسترس نیست و تنها با دسترسی مدیر(Master) در سرویس کاربران می‌توانید آن را فراخوانی کنید.

نمونه‌ای از این درخواست به صورت زیر است:

curl -X POST \
    --header "Authorization: Bearer 32672…" \
    --header "X-Backtory-Storage-Id: 125653265" \
    --header "Content-Type: application/json" \
    -d \
    '{
        "url" : "/path1/path2/",
        "pageNumber" : 1,
        "pageSize" : 10,
        "sortingType" : "ASC"
    }'  \
    http://storage.backtory.com/files/directoryInfo

درخواست بالا بدین معنی است که قصد داریم زیر فایل‌ها و پوشه‌هایی که در مسیر /path1/path2/ هستند را ببینیم. مقدار pageNumber=1 نیز به بکتوری می‌گوید که به دنبال صفحه دوم اطلاعات هستیم، یعنی شروع صفحه از صفر شروع می‌شود. مقدار pageSize=10 نیز نشان می‌دهد که انتظار داریم حداکثر ۱۰ رکورد برگردد. در مجموع منظور از این درخواست آن است که ما به دنبال رکوردهای ۱۱ام تا ۲۰ام هستیم. به تعبیر دیگر رکوردهایی با اندیس ۱۰ تا ۱۹. بنابر این اگر به دنبال صفحه اول اطلاعات هستید باید pageNumber برابر 0 باشد.

بکتوری پاسخی مشابه زیر خواهد داد:

{
  "files" : [{
    "guid" : "76432455326532764837baacdff",
    "url" : "pegah/path1/path2/x1.txt",
    "ownerId" : "76432455326532764837baacdfe",
    "isDirectory" : false,
    "fileSizeInBytes" : 276372,
    "numberOfDirectChildren" : 0,
    "numberOfTotalChildren" : 0
  }]
}

آنچه از پاسخ بکتوری مشخص است آن است که در صفحه دوم اطلاعات فقط یک فایل وجود دارد. بنابر این، در پوشه /path1/path2/ تنها ۱۱ فرزند مستقیم وجود دارد (۱۰ فرزند در صفحه اول و یک فرزند در صفحه دوم). همانطور که می‌بینید این فرزند در مسیر pegah/path1/path2/x1.txt قرار دارد. بنابر این مسیر دانلود آن به صورت زیر است:

http://storage.backtory.com/pegah/path1/path2/x1.txt

همچنین این فرزند یک فایل است چون isDirectory آن برابر false است و حجم فایل نیز برابر است با 276372 بایت. تعداد فرزندان مستقیم آن صفر و تعداد کل فرزندان (شامل تمام زیرپوشه‌های آن به صورت بازگشتی) نیز صفر است. این اعداد در صورتی که رکورد مورد نظر فایل باشد حتما صفر خواهد بود چون فایل نمی‌تواند زیرفایل داشته باشد، اما در صورتی که پوشه باشد و درون آن محتویاتی باشد غیرصفر خواهد بود.

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

Tables Description
200-OK Successfully uploaded
400-Bad Request Your request syntax is not correct
401-Unauthorized Unauthorized access to instance
500-Internal Server Error Backtory server failed to respond

حذف فایل/پوشه

در صورتی که قصد حذف یک یا چند فایل/پوشه را دارید، باید از این سرویس استفاده کنید. نمونه ساده‌ای از فراخوانی این درخواست به صورت زیر است:

curl -X POST \
    --header "Authorization: Bearer 4786487…" \
    --header "X-Backtory-Storage-Id: 125653265" \
    --header "Content-Type: application/json" \
    -d \
    '{
        "urls" : ["/path1/file1.mp3","/path1/child_directory/"],
        "forced" : [false, true]
    }' \ 
    http://storage.backtory.com/files/delete

در بدنه درخواست بالا فیلد urls آدرس پوشه‌ها و فایل‌هاییست که قصد حذف آنها را داریم. فیلد forced نیز که یک آرایه هم‌اندازه با urls است بیانگر آن است که هر عضو متناظر آن در urls باید به زور حذف شود یا خیر. حذف به زور بدین معنا است که اگر آدرس مورد نظر پوشه باشد و درون خود فایل‌هایی داشته باشد باید با تمامی فایل‌های داخلی حذف شود. در صورتی که شما مقدار forced را برای یک پوشه برابر false بگذارید و آن پوشه، زیر پوشه‌ها یا فایل‌هایی داشته باشد، عملیات حذف با شکست مواجه خواهد شد.

نکاتی که در مورد درخواست حذف باید رعایت کنید:

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

Tables Description
200-OK Successfully uploaded
400-Bad Request Your request syntax is not correct
401-Unauthorized Unauthorized access to instance
404-Not Found Files/Directories not found
417-Expectation Failed More than 1000 files/not same parents
500-Internal Server Error Backtory server failed to respond

کپی فایل/پوشه

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

توجه:‌ این سرویس از طریق اپ موبایل قابل دسترس نیست و تنها با دسترسی مدیر (Master) در سرویس کاربران می‌توانید آن را فراخوانی کنید.

نمونه‌ای از درخواست به صورت زیر است:

curl -X POST \
    --header "Authorization: Bearer 47383…" \
    --header "X-Backtory-Storage-Id: 125653265" \
    --header "Content-Type: application/json" \
    -d \
    '{
        "sourceUrls" : ["/path1/path2/path3/", "/path1/path2/x.txt"],
        "forces" : [true, false],
        "destinationUrl" : "/path1/path4/"
    }' \
    http://storage.backtory.com/files/copy

همانطور که می‌بینید قصد داریم پوشه path3 و فایل a.txt که هر دو در مسیر /path1/path2/ قرار دارند را به آدرس /path1/path4/ کپی کنیم.

بکتوری در پاسخ یکی از کدهای زیر را به عنوان جواب بازخواهد گرداند:

Tables Description
200-OK Successfully uploaded
400-Bad Request Your request syntax is not correct
401-Unauthorized Unauthorized access to instance, uesr MASTER
404-Not Found Files/Directories not found
417-Expectation Failed More than 100 files/not same parents/your service disabled/etc.
500-Internal Server Error Backtory server failed to respond

جابه‌جایی فایل/پوشه

عملی جابه‌جایی در سرویس فایل معادل Cut در سیستم‌عامل ویندوز و یا Move در لینوکس است. شما تعدادی از منابع را انتخاب و مقصدی که باید جابه‌جایی انجام گیرد را نیز مشخص می‌کنید و عملیات جابه‌جایی انجام می‌شود. نکاتی که باید رعایت کنید عبارتند از:

توجه:‌ این سرویس از طریق اپ موبایل قابل دسترس نیست و تنها با دسترسی مدیر (Master) در سرویس کاربران می‌توانید آن را فراخوانی کنید.

نمونه‌ای از درخواست به صورت زیر است:

curl -X POST \
    --header "Authorization: Bearer 47383…" \
    --header "X-Backtory-Storage-Id: 125653265" \
    --header "Content-Type: application/json" \
    -d \
    '{
        "sourceUrls" : ["/path1/path2/path3/", "/path1/path2/x.txt"],
        "forces" : [true, false],
        "destinationUrl" : "/path1/path4/"
    }'
    http://storage.backtory.com/files/move

همانطور که می‌بینید قصد داریم پوشه path3 و فایل a.txt که هر دو در مسیر /path1/path2/ قرار دارند، را به آدرس /path1/path4/ جابه‌جا کنیم.

بکتوری در پاسخ یکی از کدهای زیر را به عنوان جواب بازخواهد گرداند:

Tables Description
200-OK Successfully uploaded
400-Bad Request Your request syntax is not correct
401-Unauthorized Unauthorized access to instance, user MASTER
404-Not Found Files/Directories not found
417-Expectation Failed More than 100 files/not same parents/your service disabled/etc.
500-Internal Server Error Backtory server failed to respond

تغییر نام فایل (Rename)

در صورتی که قصد دارید نام یک فایل را تغییر دهید بایستی از این سرویس استفاده کنید. این امکان برای پوشه‌ها در بکتوری وجود ندارد.

نمونه‌ای از درخواست تغییر نام به صورت زیر است:

curl -X POST \
    --header "Authorization: Bearer 78276432…" \
    --header "X-Backtory-Storage-Id: 125653265" \
    --header "Content-Type: application/json" \
    -d \
        '{
            "items" : [
                {
                    "pathToRename": "/path1/path2/file1.txt",
                    "newFileName": "newFile1.txt"
                },
                {
                    "pathToRename": "/path1/path2/file2.txt",
                    "newFileName": "newFile2.txt"
                }
            ]
        }' \
    http://storage.backtory.com/files/rename

در درخواست بالا ما دو فایل file1.txt و file2.txt را به newFile1.txt و newFile2.txt تغییر نام دادیم.

بکتوری در پاسخ، مشابه سرویس آپلود آدرس جدید فایل‌ها را برای شما ارسال خواهد کرد. برای مثال پاسخ درخواست بالا مشابه زیر است:

{
  "newPaths": [
    "/path1/path2/newFile1.txt",
    "/path1/path2/newFile2.txt"
  ]
}

دقت کنید که اگر فایل‌های شما کاراکترهای خاص و یا فارسی داشته باشد پاسخ بکتوری مهم خواهد بود. برای مثال اگر شما به جای نام newFile1.txt مقدار newFile 1&.txt وارد کنید. یعنی یک کاراکتر فاصله اضافه و یک علامت & بگذارید، پاسخ بکتوری به صورت زیر خواهد بود:

{
  "newPaths": [
    "/path1/path2/newFile%201%26.txt",
    "/path1/path2/newFile2.txt"
  ]
}

و آدرس دانلود فایل نیز به صورت زیر خواهد بود:

http://storage.backtory.com/pegah/path1/path2/newFile%201%26.txt

به این ترتیب، شما با تمامی اعمال لازم برای مدیریت فایل‌ها و پوشه‌ها آشنا شده‌اید.