跳转到正文
皓量云擎文档

调用约定

理解版本化路径、响应封装、分页、幂等和异步任务。

URL 与请求

使用平台提供的同源 HTTPS 入口,管理接口常用 /api/v1/,认证接口为 /api/auth/v1/,部分平台管理接口位于 /api/admin/v1/。各方法和路径以参考页为准。

JSON 写请求设置 Content-Type: application/json。未定义字段可能被拒绝,不在请求中追加内部主机地址、文件路径或其他契约未声明字段。

响应

常见 JSON 封装为 data 与 request_id,错误为 error 与 request_id。健康检查、文件下载和特殊通道可能不同,应按单接口的响应媒体类型处理。

{
  "data": {"id": "<任务 UUID>", "resource_id": "<资源 UUID>", "state": "queued"},
  "request_id": "<请求标识>"
}

该示例表示任务已受理,不表示资源已创建。data.id 在不同接口可能是任务或资源身份,必须按具体操作语义解释。

分页与范围

只对声明分页参数的接口发送 page、page_size,不要假定所有列表有同一封装或默认大小。显式租户参数不能替代授权;当前工作区、默认租户和关联资源归属见租户上下文。

其他约定

  • 资源身份使用 UUID,名称用于显示,不解析名称生成资源路径。
  • 容量字段如 size_gib 以 GiB 表示,时间按契约的 date-time 处理。
  • 支持的写操作使用 Idempotency-Key,同次业务重试保留原键和参数。
  • HTTP 200 的任务响应继续轮询任务;文件下载按响应类型保存,不强行解析 JSON。
  • API 参考的 JSON 结构是字段定义,不是可以直接提交的业务示例。

本页目录