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

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

پیش‌نیازها

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

این مستند به شما کمک خواهد کرد تا با عملیات پیچیده‌ای که توسط سیستم فایل قابل انجام است، آشنا شوید و نحوه فراخوانی آنها را از طریق 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 retrieved info
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 32672…" \
    --header "X-Backtory-Storage-Id: 125653265" \
    --header "Content-Type: application/json" \
    -d \
    '{
        "url" : "/path1/path2/"
    }'  \
    http://storage.backtory.com/files/fileInfo

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

{
    "guid": "5aaa6d046e2e81f9e88ef2d1",
    "url": "notduplicate/dir1/file1.txt",
    "ownerId": null,
    "creationDate": 1521118468205,
    "lastModificationDate": 1521118468205,
    "fileSizeInBytes": 131072,
    "realFileSizeInBytes": 23,
    "md5Hash": "3442267f06078e79a8b63cabc1802b1d",
    "crcHash": "fa45e246",
    "thumbnails": null,
    "defaultThumbnail": null,
    "metaData": null
}

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

Tables	Description
200-OK	Successfully retrieved info
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 بگذارید و آن پوشه، زیر پوشه‌ها یا فایل‌هایی داشته باشد، عملیات حذف با شکست مواجه خواهد شد.

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

تمامی url هایی که درخواست حذف آنها را دارید باید متعلق به یک پدر یکسان باشند. برای مثال در نمونه curl بالا، هر دو url در پوشه /path1/ هستند و اگر اینطور نبود عملیات حذف با شکست مواجه می‌شد.
تعداد فایل‌هایی که باید حذف شود نباید بیشتر از ۱۰۰۰ باشد. تعداد فایل‌ها برابر است با تعداد فایل‌هایی که مستقیم درخواست حذف داده‌اید، به علاوه تعداد زیرفایل‌های پوشه‌هایی که در خواست حذف آنها را داده‌اید.
در صورتی که قصد حذف یک پوشه غیر تهی (دارای زیر پوشه‌ها یا فایل‌های داخلی) را دارید، حتما باید مقدار forced متناظر با آن پوشه true باشد.
شما نمی‌توانید کل مخزن را حذف کنید. یعنی درخواست حذف برای آدرس / با شکست مواجه خواهد شد.

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

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

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

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

‌ محدودیت تعداد اعضایی که در یک عمل قابل کپی شدن هستند ۱۰۰ است. یعنی تعداد المان‌ها و فرزندان آنها مجموعا باید کمتر از ۱۰۰ باشد.
همه منابعی که قصد کپی آنها را داریم باید در یک پدر مشترک قرار داشته باشند. برای مثال اگر قصد کپی کردن a.txt و b.txt را دارید، هر دو فایل باید در یک پوشه یکسان قرار داشته باشند.
در صورتی که فایل‌هایی که کپی می‌کنید در مقصد موجود باشند، باید مقدار forced را در درخواست true قرار دهید. در غیر این صورت عملیات کپی با شکست مواجه خواهد شد. دقت کنید که مقدار forced یک آرایه از مقادیر true و false است که متناظر با هر یک از منابع درخواست شده است. (مراجعه به نمونه درخواست پایین)
در صورتی که پوشه‌هایی که کپی می‌کنید از قبل وجود داشته باشند، بکتوری به صورت پیش‌فرض آنها را با هم ادغام (Merge) خواهد کرد.

توجه:‌ این سرویس از طریق اپ موبایل قابل دسترس نیست و تنها با دسترسی مدیر (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 در لینوکس است. شما تعدادی از منابع را انتخاب و مقصدی که باید جابه‌جایی انجام گیرد را نیز مشخص می‌کنید و عملیات جابه‌جایی انجام می‌شود. نکاتی که باید رعایت کنید عبارتند از:

‌ محدودیت تعداد اعضایی که در یک عمل قابل جابه‌جایی شدن هستند ۱۰۰ است. یعنی تعداد المان‌ها و فرزندان آنها مجموعا باید کمتر از ۱۰۰ باشد.
همه منابعی که قصد جابه‌جایی آنها را داریم باید در یک پدر مشترک قرار داشته باشند. برای مثال اگر قصد کپی کردن a.txt و b.txt را دارید، هر دو فایل باید در یک پوشه یکسان قرار داشته باشند.
در صورتی که فایل‌هایی که جابه‌جا می‌کنید در مقصد موجود باشند، باید مقدار forced را در درخواست true قرار دهید. در غیر این صورت عملیات جابه‌جایی با شکست مواجه خواهد شد. دقت کنید که مقدار forced یک آرایه از مقادیر true و false است که متناظر با هر یک از منابع درخواست شده است. (مراجعه به نمونه درخواست پایین)
در صورتی که پوشه‌هایی که جابه‌جا می‌کنید از قبل وجود داشته باشند، بکتوری به صورت پیش‌فرض آنها را با هم ادغام (Merge) خواهد کرد.

توجه:‌ این سرویس از طریق اپ موبایل قابل دسترس نیست و تنها با دسترسی مدیر (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": [
    "/bucketName/path1/path2/newFile1.txt",
    "/bucketName/path1/path2/newFile2.txt"
  ]
}

دقت کنید که در پاسخ سرور، bucketName همان نام مخزن شما می‌باشد.

دقت کنید که اگر فایل‌های شما کاراکترهای خاص و یا فارسی داشته باشد پاسخ بکتوری مهم خواهد بود. برای مثال اگر شما به جای نام 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

امکانات دانلود

هنگام دانلود یا نمایش فایل‌ها در مرورگر بکتوری امکاناتی در اختیار شما قرار می‌دهد که در این بخش به شرح آن‌ها می‌پردازیم.

تغییر سایز تصاویر

در صورتی که تصویری روی سرور بکتوری داشته ‌باشید، هنگام دانلود یا نمایش ‌آن می‌توانید سایزش را به دلخواه خودتان تغییر دهید. برای این کار کافیست به انتهای آدرس تصویر

r/<number>x<number>/

را اضافه کنید.

نمونه درخواست:

curl -X GET \
    https://storage.backtory.com/<bucket-name>/<directory>/<image-name>/r/<size>x<size>

برای مثال:

 https://storage.backtory.com/notduplicate/dir1/image1.jpg/r/300x300

شخصی‌سازی نام فایل

هنگام دانلود یک فایل در صورت اضافه کردن کوئری پارامتر name یا filename با مقدار دلخواه شما به URL، نام فایلی که برای شما فرستاده‌ می‌شود، برابر مقدار تعیین شده در این هدر خواهد ‌بود.

دقت کنید که حروف فارسی پشتیبانی نمی‌شوند، همچنین استفاده از کاراکتر‌هایی مثل & و # و % باعث اشکال می‌شوند.