OpenAPI 云磁盘管理

本页介绍云磁盘的创建、列表、重命名、扩容和释放。请求均需携带 OpenAPI 鉴权 Header。

需重点关注

释放云磁盘会删除其中的数据。调用释放接口前，请确认云磁盘已卸载且数据已经备份。

接口列表

操作	方法	路径
创建云磁盘	POST	/api/storage/cloud_disk/create
查询云磁盘列表/详情	GET	/api/storage/cloud_disk/list
重命名云磁盘	POST	/api/storage/cloud_disk/rename
扩容云磁盘	POST	/api/storage/cloud_disk/resize
释放云磁盘	POST	/api/storage/cloud_disk/release

云磁盘暂未提供单独的详情接口；列表接口的每条记录已经包含容量、状态、挂载关系等详情。

创建云磁盘

创建前先调用云磁盘规格接口，获取 spec_id 和最大容量。

POST /api/storage/cloud_disk/create
Content-Type: application/json

字段	类型	必填	说明
size_gb	integer	是	容量，最小 20 GB，且不能超过规格的 max_size_g
spec_id	integer	是	云磁盘规格 ID
disk_name	string	否	云磁盘名称
mount_path	string	否	默认挂载路径；必须为绝对路径，不能使用系统受保护目录
purchase_duration	integer	否	当前按需创建建议传 1

禁止使用 /、/root、/mnt、/var，以及 /tmp、/dev、/proc、/sys、/etc、/usr、/boot 等系统目录或其子目录作为挂载路径。

curl -X POST "$DAMODEL_API/api/storage/cloud_disk/create" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{
    "size_gb": 100,
    "spec_id": 3,
    "disk_name": "dataset-01",
    "mount_path": "/root/workspace/dataset-01",
    "purchase_duration": 1
  }'

成功时 result 为 null。创建是异步过程，应通过列表接口轮询状态，直到变为 2（可用）。

创建错误

code_n	code	说明
100002	InvalidParameter	容量、规格 ID 或挂载路径不合法
100038	BalanceNotEnough	主账号余额不足，具体错误可能由下游计费服务返回
180009	CreateCloudDiskError	云磁盘创建失败
100014	InternalError	规格查询、订单或存储服务失败

查询云磁盘列表

GET /api/storage/cloud_disk/list

参数	位置	类型	必填	说明
page	Query	integer	是	页码
page_size	Query	integer	是	每页数量，0 表示返回全部
name_or_uid	Query	string	否	按名称或云磁盘 UID 模糊搜索
status	Query	integer	否	按状态筛选
spec_types	Query	integer[]	否	逗号分隔；1 RBD、2 FS、3 S3
cluster_id	Query	integer	否	按集群 ID 筛选
support_ib_network	Query	integer	否	IB 网络筛选预留参数，当前版本不保证筛选生效

curl "$DAMODEL_API/api/storage/cloud_disk/list?page=1&page_size=20&name_or_uid=dataset" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)"

result 为分页对象，云磁盘记录位于 result.data。

字段	类型	说明
id	integer	云磁盘数据库 ID，重命名、扩容和释放时使用
uid	string	云磁盘 UID，创建实例挂载已有云磁盘时使用
name	string	云磁盘名称
size_gb	integer	容量，单位 GB
status	integer	云磁盘状态，见下表
spec_id / spec_type	integer/string	规格信息
storage_class_type	integer	1 RBD、2 FS、3 S3
multiple_mounting	boolean	是否支持多实例同时挂载
mount_path	string	默认挂载路径
binding_instances	array	普通实例挂载关系
binding_clusters	array	集群挂载关系
release_with_instance	boolean	是否随实例释放
release_with_cluster	boolean	是否随集群释放
create_time / stop_time	integer	Unix 秒级时间戳

状态值：

值	状态
1	启动中
2	可用
3	挂载中
4	卸载中
5	释放中
6	已挂载
7	已释放
8	欠费

{
  "result": {
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_page": 1,
    "data": [
      {
        "id": 321,
        "uid": "disk-6f6ccf",
        "name": "dataset-01",
        "size_gb": 100,
        "status": 2,
        "spec_id": 3,
        "spec_type": "超速文件存储",
        "storage_class_type": 2,
        "multiple_mounting": true,
        "mount_path": "/root/workspace/dataset-01",
        "binding_instances": [],
        "binding_clusters": []
      }
    ]
  },
  "response_metadata": {
    "request_id": "request-id",
    "trace_id": "trace-id",
    "action": "",
    "version": "",
    "service": "",
    "error": null
  }
}

重命名云磁盘

POST /api/storage/cloud_disk/rename

curl -X POST "$DAMODEL_API/api/storage/cloud_disk/rename" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{"id": 321, "name": "dataset-prod"}'

成功时 result 为 null。id 必须是列表接口返回的数据库 ID，而不是 uid。

扩容云磁盘

POST /api/storage/cloud_disk/resize

curl -X POST "$DAMODEL_API/api/storage/cloud_disk/resize" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{"id": 321, "size_gb": 200}'

字段	类型	必填	说明
id	integer	是	云磁盘数据库 ID
size_gb	integer	是	扩容后的目标总容量，不是增量；只能扩大，不能缩小

成功时 result 为 null。扩容可能异步完成，请查询列表确认 size_gb 和状态。

释放云磁盘

POST /api/storage/cloud_disk/release

curl -X POST "$DAMODEL_API/api/storage/cloud_disk/release" \
  -H "Content-Type: application/json" \
  -H "X-Damodel-Token: $DAMODEL_TOKEN" \
  -H "X-Damodel-Timestamp: $(date +%s)" \
  -d '{"id": 321}'

成功时 result 为 null，表示释放任务已受理。已挂载或状态不允许释放时，下游服务会返回相应业务错误。

操作类接口常见错误

code_n	code	说明
100002	InvalidParameter	ID、名称、容量或路径不合法
100006	InvalidToken	API Key 或时间戳无效
100042	PermissionDenied	子账号没有云磁盘管理权限
100014	InternalError	云磁盘、订单或存储服务调用失败