واجهة وحدات التخزين (قريباً)

معاينة لنقاط نهاية وحدات التخزين المجهّزة وعقد الربط. الإنشاء واحتساب الاستخدام معطّلان في الإنتاج اليوم.

يغطي عقد الواجهة المجهّز إنشاء وحدة تخزين والتحقق من حالتها وتوسيعها وربطها أو فصلها عن تطبيق عند مسار تحميل. لتجربة لوحة التحكم والمفاهيم الأساسية (قواعد الربط، المتانة، التسعير)، راجع وحدات التخزين (Block Volumes).

الميزة معطّلة في الإنتاج

توثّق هذه النقاط واجهة مجهّزة للمستقبل. يعيد الإنشاء في الإنتاج حالياً الرمز BLOCK_VOLUME_DISABLED، كما أن احتساب استخدام وحدات التخزين معطّل.

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 PVC's name (and the pvc_name an attach targets).

display_name?string

Optional; defaults to the trimmed name when omitted.

size_gb*integer

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

Response Body

`application/json`

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

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "size_gb": 0,
  "storage_class": "block-durable",
  "access_mode": "ReadWriteOnce",
  "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/volumes"

{
  "volumes": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "name": "string",
      "display_name": "string",
      "size_gb": 0,
      "storage_class": "block-durable",
      "access_mode": "ReadWriteOnce",
      "status": "provisioning",
      "status_reason": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "attached": true
    }
  ]
}

{
  "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

volumeId*string

UUID of the volume service.

Response Body

`application/json`

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

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "size_gb": 0,
  "storage_class": "block-durable",
  "access_mode": "ReadWriteOnce",
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "attachment": {
    "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
    "mount_path": "string",
    "read_only": true
  }
}

{
  "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

volumeId*string

UUID of the volume service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

size_gb*integer

The new booked capacity in GiB. Must be >= the volume's current size — PVC expansion is grow-only.

Response Body

`application/json`

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

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "size_gb": 0,
  "storage_class": "block-durable",
  "access_mode": "ReadWriteOnce",
  "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

volumeId*string

UUID of the volume service.

Response Body

`application/json`

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

Empty

{
  "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

volumeId*string

UUID of the volume service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

container_id*string

UUID of the container/web/worker service to mount the volume into.

mount_path*string

Absolute filesystem path inside the container.

read_only?boolean

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes/497f6eca-6276-4993-bfeb-53cbbbba6f08/attach" \  -H "Content-Type: application/json" \  -d '{    "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",    "mount_path": "/data"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "volume_id": "f17547b0-76cd-4153-92b9-a7d38dac0aba",
  "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
  "mount_path": "string",
  "read_only": true,
  "created_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

volumeId*string

UUID of the volume service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

container_id*string

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes/497f6eca-6276-4993-bfeb-53cbbbba6f08/detach" \  -H "Content-Type: application/json" \  -d '{    "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa"  }'

Empty

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

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

Empty

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

يُعيد كل طلب فاشل جسم JSON بالشكل { "code": "...", "message": "..." }. الرموز التي ستراها على نقاط النهاية هذه: 401 UNAUTHORIZED؛ 403 BLOCK_VOLUME_DISABLED (عند الإنشاء فقط — وحدات التخزين غير مُفعَّلة بعد على المنصّة)؛ 409 PROJECT_SUSPENDED (المشروع نفسه موقوف)؛ 402 INSUFFICIENT_BALANCE أو 403 ACCOUNT_SUSPENDED (حساب الفوترة بلا رصيد، أو موقوف) عند الإنشاء، وعند تغيير الحجم إلى قيمة أكبر — أما طلب تغيير الحجم إلى القيمة نفسها فلا يخضع أبداً لبوّابة الفوترة؛ 404 NOT_FOUND (وحدة التخزين أو التطبيق الذي لا تملكه يظهر كأنه غير موجود، دون أي تسريب)؛ 409 INSUFFICIENT_CAPACITY عند الإنشاء أو عند توسيع يتجاوز ما يستطيع حسابك حجزه؛ 400 SHRINK_NOT_SUPPORTED عند تصغير الحجم؛ وعند الربط: 409 RWO_REPLICA_LIMIT، أو 409 VOLUME_ALREADY_ATTACHED، أو 409 ALREADY_ATTACHED، أو 409 MOUNT_PATH_IN_USE.

مسار الإنشاء والجاهزية في الواجهة المجهّزة

بعد إتاحة الميزة، صُمّم POST .../volumes ليعيد فوراً الحالة status: "provisioning" بينما يُجهَّز القرص بشكل غير متزامن. يستعلم العميل بعدها GET .../volumes/{volumeId} حتى تصبح status بقيمة "running". لا تحمل وحدة التخزين الجديدة أي ربط حتى استدعاء attach.

الربط والفصل المجهّزان

يجعل العقد المجهّز POST .../volumes/{volumeId}/attach يربط قرص وحدة التخزين بالخدمة المستهدفة — تطبيق حاوية (container)، أو تطبيق ويب (web)، أو تطبيق عامل خلفي (worker) — عند mount_path، ثم يعيد تشغيلها. تُطبَّق قاعدة ReadWriteOnce من جهة الخادم:

يمكن ربط وحدة التخزين بمستهلك واحد فقط في كل مرّة (409 VOLUME_ALREADY_ATTACHED إن حاولت ربط مستهلك ثانٍ).
يجب أن تعمل الخدمة المستهدفة بنسخة واحدة كحدّ أقصى (409 RWO_REPLICA_LIMIT خلاف ذلك).
لا يمكن أن تكون لدى الخدمة المستهدفة وحدة تخزين أخرى مربوطة بالفعل عند mount_path نفسه (409 MOUNT_PATH_IN_USE).

وفي هذا العقد، يزيل POST .../volumes/{volumeId}/detach الربط ويعيد تشغيل المستهلك. تبقى وحدة التخزين نفسها دون تغيير، ويمكن ربطها بمكان آخر أو حذفها متى لم تعد أي جهة تستخدمها (DELETE .../volumes/{volumeId} يُعيد 409 VOLUME_ATTACHED طالما بقي أي ربط قائماً).

تغيير الحجم في الواجهة المجهّزة: الزيادة فقط

يقبل PATCH .../volumes/{volumeId} المجهّز قيمة size_gb جديدة يجب أن تكون أكبر من أو تساوي حجم وحدة التخزين الحالي. أي قيمة أصغر تُرفَض بـ 400 SHRINK_NOT_SUPPORTED قبل حتى استشارة بوّابة السعة — طبقة التخزين الأساسية تدعم فقط توسيع قرص حيّ، لا تصغيره أبداً.

مرجع كامل: وحدات التخزين (Block Volumes).

واجهة وحدات التخزين (قريباً)

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

409application/json

201application/json

400application/json

401application/json

404application/json

409application/json

204

400application/json

401application/json

404

في هذه الصفحة

`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`