数据库资源管理 API 用于管理 Database、Table、Retention 和业务访问令牌。当前不提供这些能力的管理 SDK；自动化程序可以直接调用 API，人工操作推荐使用 tsdb-cli。

接口清单

所有请求使用集群详情页显示的连接地址，并携带具有相应权限的访问令牌。

公共请求约定

• 推荐使用 Authorization: Bearer <token> 请求头。
• 创建或重新生成的令牌明文以 apiv3_ 开头，并且只返回一次，请立即保存。
• JSON 请求体使用 Content-Type: application/json，字段使用 snake_case。
• 列举和查看接口的 format 支持 pretty、json、json_lines（别名 jsonl）、csv 和 parquet；省略时根据 Accept 协商，未提供 Accept 时默认返回 JSON。
• 请求体大小受集群服务限制，默认上限为 10 MiB；gzip 请求按解压后的大小计算，超出限制返回 413。

Retention 格式

Retention 使用时长字符串，支持 h、d、w、mo 和 y 组合，例如 30d、2w3d、1y6mo。数据库级 null 表示永久保留；表级 null 表示清除表级设置并继承数据库。

PermissionSpec

业务 Token 可以使用以下三类权限结构：

1{"resource":"database","identifiers":["mydb"],"actions":["read","write"]}
2{"resource":"table","identifier":{"db":"mydb","table":"cpu"},"actions":["read","write"]}
3{"resource":"token","actions":["create","read","update","delete"]}

创建 Token 时不能授予超出当前调用令牌自身权限的权限。

错误处理

数据库资源管理 API 的错误响应可能是 JSON 错误对象，也可能是纯文本。客户端应先按 HTTP 状态码分类，并同时兼容两种响应体。

删除与 Retention 风险

• 删除数据库或表会删除对应数据，调用前必须核对目标资源。
• 缩短 Retention 会改变历史数据的保留范围。
• 自动化删除应设置人工审批或等价保护，不根据名称模糊匹配批量执行。