واجهة الـ Buckets

أنشئ buckets للتخزين السحابي واعرضها وغيّر سعتها واحذفها، وأعِد توليد مفاتيحها، واربطها بتطبيق.

أدِر buckets التخزين السحابي عبر الواجهة: أنشئ واحداً، تحقّق من حالته واستخدامه، غيّر سعته، أعِد توليد مفاتيح الوصول الخاصة به، واكشف بيانات الاعتماد التي تظهر مرة واحدة. لتجربة لوحة التحكم والمفاهيم الأساسية (التسمية، والسعة، وتعدّد الإصدارات)، راجع Basin.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Human-friendly name; a DNS-safe slug is derived from it and used as the bucket's physical, tenant-scoped name (never exposed directly — see GET .../credentials).

display_name?string

Optional; defaults to the trimmed name when omitted.

quota_gb*integer

Booked capacity in GiB — the billable unit (object_storage rate).

versioning?boolean

Reserved for S3 object versioning on the bucket. The setting is stored and echoed back, but versioning enforcement on the physical bucket is not yet active — do not rely on it to protect against accidental overwrites or deletes yet.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets" \  -H "Content-Type: application/json" \  -d '{    "name": "assets",    "quota_gb": 1  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "quota_gb": 0,
  "versioning": true,
  "used_bytes": 0,
  "object_count": 0,
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets"

{
  "buckets": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "name": "string",
      "display_name": "string",
      "quota_gb": 0,
      "versioning": true,
      "used_bytes": 0,
      "object_count": 0,
      "status": "provisioning",
      "status_reason": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "quota_gb": 0,
  "versioning": true,
  "used_bytes": 0,
  "object_count": 0,
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

quota_gb*integer

The new booked capacity in GiB.

versioning?boolean

When present, replaces the bucket's stored versioning setting. Omit to leave the current setting unchanged. Reserved: versioning enforcement on the physical bucket is not yet active (see Bucket.versioning).

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "quota_gb": 1  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "quota_gb": 0,
  "versioning": true,
  "used_bytes": 0,
  "object_count": 0,
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/regenerate-keys"

{
  "status": "rotating",
  "generation": 0
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials"

{
  "status": "ready",
  "generation": 0,
  "access_key_id": "string",
  "secret_access_key": "string",
  "endpoint": "https://basin.alawadi.cloud",
  "bucket": "t3f2a1b2c-assets",
  "region": "me-central-1"
}

{
  "status": "provisioning"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

الأخطاء تأتي برمز ورسالة

يُعيد كل طلب فاشل جسم JSON بالشكل { "code": "...", "message": "..." }. الرموز التي ستراها على نقاط النهاية هذه: 401 UNAUTHORIZED؛ 403 OBJECT_STORAGE_DISABLED (عند الإنشاء فقط — التخزين السحابي غير مُفعَّل بعد على هذا الحساب)؛ 409 PROJECT_SUSPENDED (المشروع نفسه موقوف)؛ 402 INSUFFICIENT_BALANCE أو 403 ACCOUNT_SUSPENDED (حساب الفوترة بلا رصيد، أو موقوف) عند الإنشاء، وعند تغيير سعة يزيدها — أما التقليص فلا يخضع أبداً لبوّابة الفوترة؛ 404 NOT_FOUND (الـ bucket الذي لا تملكه يظهر كأنه غير موجود، دون أي تسريب)؛ 409 INSUFFICIENT_CAPACITY عند الإنشاء أو عند تغيير سعة يتجاوز ما يستطيع حسابك حجزه؛ و410 ALREADY_REVEALED عند استدعاء GET .../credentials مرة ثانية لنفس جيل المفاتيح.

أنشئ، ثم استعلم حتى الجاهزية

يُعيد POST .../buckets فوراً بحالة status: "provisioning" — يُجهَّز الـ bucket وهويته على S3 بشكل غير متزامن. استعلِم GET .../buckets/{bucketId} حتى تصبح status بقيمة "running"، ثم استدعِ GET .../buckets/{bucketId}/credentials لكشف مفتاح الوصول والمفتاح السرّي. هذا الكشف يحدث مرة واحدة: يُعاد المفتاح السرّي الصريح مرة واحدة بالضبط لكل جيل مفاتيح، وأي استدعاء لاحق لنفس الجيل يُعيد 410 ALREADY_REVEALED. استدعِ regenerate-keys لتوليد جيل جديد قابل للكشف.

تصفّح الكائنات عبر لوحة التحكم أو الواجهة

يتيح لك متصفّح الملفات في لوحة التحكم (وهذه الواجهة) عرض كائنات (objects) الـ bucket الجاهز ("running") بالفعل، ورفعها، وتنزيلها، وحذفها، دون الحاجة إلى عميل S3.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Query Parameters

prefix?string

Restrict the listing to keys under this prefix (default the bucket root).

cursor?string

Continuation token from a previous page's next_cursor.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects"

{
  "prefix": "string",
  "folders": [
    "images/",
    "docs/"
  ],
  "objects": [
    {
      "key": "docs/report.pdf",
      "size": 0,
      "last_modified": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

file*file

key*string

Full destination object key, e.g. docs/report.pdf.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects" \  -F file="string" \  -F key="string"

{
  "key": "string",
  "size": 0
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Query Parameters

key*string

Full object key to delete.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects?key=string"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Query Parameters

key*string

Full object key to download.

Response Body

`application/octet-stream`

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects/content?key=string"

"string"

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

يسرد GET .../objects مستوى مجلد واحد في كل مرة — folders هي بادئات "المجلدات الفرعية" تحت prefix، وobjects هي الملفات المباشرة تحته. تصفّح أكثر من 200 عنصر عبر cursor. الرفع (POST .../objects، بصيغة multipart/form-data بحقلي file وkey) محدود بـ 100 ميغابايت؛ الملفات الأكبر تحتاج عميل S3 ببيانات اعتماد الـ bucket بدلاً من ذلك (راجع مفاتيح الوصول) — مسار رفع بروابط موقَّعة مسبقاً (presigned URL) ومتعدد الأجزاء للملفات الأكبر داخل لوحة التحكم على خارطة الطريق. أما التنزيل (GET .../objects/content?key=...) فيُبَثّ عبر الواجهة. رموز جديدة على هذه النقاط الأربع: 409 BUCKET_NOT_READY (الـ bucket لم يُكمل تجهيزه بعد)؛ 413 OBJECT_TOO_LARGE (رفع أكبر من 100 ميغابايت)؛ 400 BAD_KEY (مفتاح فارغ أو مطلق أو يحتوي ..)؛ و503 OBJECT_STORE_UNAVAILABLE (التخزين السحابي غير مُهيَّأ هنا).

اربط bucket بتطبيق

يمكن ربط bucket بتطبيق بنفس طريقة ربط قاعدة بيانات مُدارة: يستقبل التطبيق بيانات اعتماد الـ bucket كمتغيّرات بيئة، موصولة عبر مرجع سرّي، لا كنص صريح تنسخه وتلصقه.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

consumer_service_id*string

A generic container in the same project.

provider_service_id*string

The managed database or bucket to link in.

link_type*string

Must match the provider's service type: postgres, mysql, redis, or bucket (http links a plain container's URL instead).

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/service-links" \  -H "Content-Type: application/json" \  -d '{    "consumer_service_id": "23570cdd-ac17-47d2-bcbc-c7128eb2ba97",    "provider_service_id": "17062ceb-e6d9-456f-9abb-e8f6605cc7cc",    "link_type": "http"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "consumer_service_id": "23570cdd-ac17-47d2-bcbc-c7128eb2ba97",
  "provider_service_id": "17062ceb-e6d9-456f-9abb-e8f6605cc7cc",
  "link_type": "http",
  "injected_env": {
    "property1": "string",
    "property2": "string"
  }
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

اضبط provider_service_id على الـ bucket وlink_type على bucket. يكتسب التطبيق (المستهلك) هذه المتغيّرات في بيئته:

المتغيّر	القيمة
`AWS_ACCESS_KEY_ID`	مفتاح وصول الـ bucket
`AWS_SECRET_ACCESS_KEY`	المفتاح السرّي للـ bucket
`S3_ENDPOINT`	`https://basin.alawadi.cloud`
`S3_BUCKET`	اسم الـ bucket الكامل المُسبَّق بالبادئة
`S3_REGION`	`me-central-1`

الـ buckets المُنشأة قبل إعادة تسمية المنطقة تحقن damm-1 هنا؛ وهو اسم بديل (alias) دائم لـ me-central-1، لذا تبقى التطبيقات المربوطة تعمل بلا تغيير.

تشير هذه المتغيّرات إلى نفس نقطة النهاية المتوافقة مع S3 التي يشرحها دليل ربط تطبيق يدوياً — رابط الخدمة فقط يصل هذه المتغيّرات نيابةً عنك بدل أن تنسخ القيم من كشف بيانات الاعتماد. إن أعدت توليد مفاتيح الـ bucket عبر regenerate-keys، تُعاد تشغيل كل التطبيقات المربوطة به تلقائياً لتلتقط بيانات الاعتماد الجديدة.

مرجع كامل: نظرة عامة على Basin · مفاتيح الوصول · ربط تطبيق بالتخزين السحابي.

واجهة الـ Buckets

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

200application/json

401application/json

404application/json

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

409application/json

204

401application/json

404application/json

202application/json

401application/json

404application/json

200application/json

202application/json

401application/json

404application/json

410application/json

200application/json

401application/json

403application/json

404application/json

409

503

201application/json

400application/json

401application/json

403application/json

404application/json

409

413

503

204

400application/json

401application/json

403application/json

404application/json

409

503

200application/octet-stream

400application/json

401application/json

403application/json

404application/json

409

503

201application/json

400application/json

401application/json

404application/json

409application/json

في هذه الصفحة

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/octet-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`