ذخیره‌سازی و باکت

پیش‌نیاز و هزینه

برای این سناریو، متغیرهای شروع سریع، حساب فعال، شمارهٔ تأییدشده و نقش مالک، مدیر یا عضو پروژه لازم است؛ نقش محدود اجازهٔ مدیریت منابع ندارد.

توجه: ساخت باکت منبع واقعی ایجاد می‌کند و هزینهٔ سرویس دارد؛ ظرفیت تخصیص‌یافته مبنای ظرفیت سرویس است و نباید آن را صرفاً هزینهٔ فایل‌های مصرف‌شده فرض کنید؛ تعرفهٔ جاری را پیش از ساخت در کنسول بررسی کنید.

ساخت باکت خصوصی

نامی یکتا انتخاب کنید؛ نام باکت بین ۵ تا ۶۳ نویسه از حروف کوچک انگلیسی، اعداد، نقطه و خط تیره است، با حرف یا عدد شروع و تمام می‌شود و دو نقطهٔ متوالی ندارد.

نمونهٔ زیر با ابزار jq پاسخ ساخت را برای استخراج آدرس ذخیره‌سازی بررسی می‌کند؛ نام را با نام یکتای متعلق به خودتان جایگزین کنید.

export ABRBIT_BUCKET='my-unique-api-demo'
BUCKET_JSON=$(curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"bucket_name\":\"$ABRBIT_BUCKET\",\"capacity\":10,\"is_public\":false}") && \
  printf '%s\n' "$BUCKET_JSON" | jq '{name,status,endpoint,capacity}'

پاسخ موفق با وضعیت 201 شیء باکت است؛ ظرفیت بر حسب GiB و بین ۱۰ تا ۳۰۰ است، و برای ادامه باید وضعیت READY باشد.

نام پس از ساخت قابل تغییر نیست؛ برای داده‌های حساس باکت خصوصی بسازید و کلیدها و لینک‌های اشتراک را محرمانه نگه دارید.

فهرست و بررسی وضعیت

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/$ABRBIT_BUCKET/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

فهرست با پوشش objects و meta و جزئیات به‌صورت شیء مستقیم برمی‌گردد؛ این فهرست صفحه‌بندی ندارد.

فیلدهای used_bytes و objects_count به مصرف مربوط‌اند؛ ظرفیت capacity را با تعداد بایت مصرف‌شده اشتباه نگیرید.

وضعیت‌های باکت شامل PENDING، READY، FAILED، DELETING و DELETE_FAILED هستند؛ هنگام حذف در حال اجرا، از ارسال تغییرات دیگر خودداری کنید.

ساخت کلید دسترسی فایل‌ها

توکن API برای مدیریت باکت است؛ برای انتقال فایل به کلیدهای سازگار با S3 نیاز دارید.

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/$ABRBIT_BUCKET/keys/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"description":"my-integration","permission":"READ_WRITE"}'

پاسخ 201 شامل id، access_key، secret_key و سایر فیلدهای کلید است؛ مقدار secret_key فقط در همین پاسخ نمایش داده می‌شود.

سطح READ_ONLY برای خواندن، سطح WRITE_ONLY برای نوشتن و سطح READ_WRITE برای هر دو است؛ کمترین دسترسی موردنیاز برنامه را انتخاب کنید.

برای ادامه، فایل را طبق راهنمای انتقال با S3 ارسال و دریافت کنید؛ آدرس endpoint را از پاسخ جزئیات باکت بردارید.

فهرست و ابطال کلید

curl --fail-with-body --silent --show-error \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/$ABRBIT_BUCKET/keys/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

پاسخ فهرست شامل objects و meta است و کلید محرمانه را تکرار نمی‌کند؛ برای حذف دسترسی برنامه، شناسهٔ عددی کلید همان باکت را قرار دهید.

توجه: حذف کلید، دسترسی برنامه‌های استفاده‌کننده از آن را قطع می‌کند.

export ABRBIT_KEY_ID='KEY_ID'
curl --fail-with-body --silent --show-error --request DELETE \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/$ABRBIT_BUCKET/keys/$ABRBIT_KEY_ID/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

پاسخ موفق 200 شامل {"message":"object deleted"} است.

تغییر ظرفیت یا عمومی بودن

curl --fail-with-body --silent --show-error --request PATCH \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/$ABRBIT_BUCKET/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"capacity":20,"is_public":false}'

پاسخ موفق 200 شیء باکت است؛ فقط فیلدهای لازم را بفرستید و ظرفیت را پایین‌تر از مصرف واقعی قرار ندهید.

افزایش ظرفیت می‌تواند هزینه را تغییر دهد؛ عمومی کردن باکت امکان دریافت بدون احراز هویت فایل از آدرس مستقیم آن را فراهم می‌کند، حتی اگر فهرست فایل‌ها عمومی نباشد.

حذف امن باکت خالی

توجه: این دستور باکت آزمایشی را حذف می‌کند؛ ابتدا فایل آزمایشی را با روش توضیح‌داده‌شده در راهنمای S3 پاک کنید.

curl --fail-with-body --silent --show-error --request DELETE \
  "$ABRBIT_API/api/v1/project/$ABRBIT_PROJECT/s3/buckets/$ABRBIT_BUCKET/" \
  --header "Authorization: Bearer $ABRBIT_TOKEN"

پاسخ موفق 200 رشتهٔ JSON برابر "deleted" است؛ پاسخ 409 یعنی باکت خالی نیست و حذف معمولی فایل‌ها را به‌زور پاک نمی‌کند.

برای باکت دارای نسخه‌بندی، نسخه‌های قبلی و نشانگرهای حذف نیز مهم‌اند؛ حذف دائمی جمعی، نسخه‌بندی، نگهداری قانونی و عملیات پیشرفته در این انتشار مستند نشده‌اند و نباید برای پاک‌سازی آن‌ها از حلقهٔ حذف عمومی استفاده کنید.