# 云存储 Local API

通过 MoreLogin Local API 管理 MoreLogin 云存储的文件、上传、删除和文件标签。
**Base URL**：`http://127.0.0.1:40000`
Local API 的路径使用 `/api` 前缀。

Version: 2026-09-05

## Servers

```
http://127.0.0.1:40000
```

## Download OpenAPI description

 - [云存储 Local API](https://guide.morelogin.com/_bundle/@l10n/zh/API%20Reference/Cloud%20Storage/local-api.yaml)

## Cloud Storage

 - [GET /api/cloudstorage/info](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage/querycloudstorageinfolocal.md): 返回团队的云存储容量与当前用量。 - **前置条件**：团队必须已有云存储记录。**从未开通过云存储的团队会收到错误，而不是读到零容量**——该记录在购买存储时创建，不会由本接口惰性创建。 - **副作用**：无。只读。可带退避安全重试。 - **单位**：`capacity` 与 `usedCapacity` 都是字节数。 - **精度**：`usedCapacity` 是在上传与删除时维护的累
## Cloud Storage Files

 - [POST /api/cloudstorage/file/page](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-files/pagecloudstoragefileslocal.md): 分页列出云存储文件。 - **副作用**：无。只读。可带退避安全重试。 - **可见性**：**只列出已确认上传完成的文件**——拿了预签名 URL 但从未完成登记的文件不会出现。没有全量数据权限的成员只能看到自己上传的文件。 - **筛选**：`fileName` 为模糊匹配；`tagIds` 为「命中任一即返回」；结果按创建时间倒序，顺序不可更改。 - **注意**：如果某个标签在仍挂在文件上
 - [POST /api/cloudstorage/upload/init](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-files/batchrequestcloudstoragepresigneduploadurlslocal.md): 预留云存储记录并获取预签名上传 URL。 - **前置条件**：团队必须已有云存储记录且未过期。每个文件基础名限 60 字符，且必须在本次请求内以及与团队现有全部文件之间唯一——**比对时不含扩展名**，因此 `a.png` 会与已存在的 `a.mp4` 冲突。 - **限制**：全团队最多同时存在 100 个未确认的上传。 - **副作用**：为每个文件名插入一条上传中状态、大小为 0 的记录，
 - [POST /api/cloudstorage/upload/complete](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-files/confirmcloudstorageuploadcompletelocal.md): 确认已上传的云存储文件。 - **前置条件**：文件记录必须属于你的团队，且对象必须已在存储中——服务端会读取其 ETag 与长度进行核验。大小必须大于 0 且小于 2 GB。 - **副作用**：原子地扣减团队存储容量，然后把记录标记为已上传并写入真实大小。在此成功之前，该文件**不会出现在 `/cloudstorage/file/page`**，并持续占用 100 个待确认槽位之一。 - **
 - [POST /api/cloudstorage/file/delete/batch](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-files/batchdeletecloudstoragefileslocal.md): 按 ID 删除云存储文件。 - **前置条件**：每个 ID 都必须能在你的团队中解析；**只要有一个解析不到，整批都会被拒绝并回滚**，包括那些已被删除的 ID。 - **副作用**：软删除。配额在同一事务内释放；已存储的对象以尽力而为的方式删除——存储侧失败只记日志、不会让调用失败，因此对象可能比记录活得更久。标签关联不会被清理。 - **完成信号**：同步。请用 `/cloudstorage
## Cloud Storage File Tags

 - [POST /api/cloudstorage/file/tag/set](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-file-tags/setcloudstoragefiletagslocal.md): 替换云存储文件上的标签。 - **前置条件**：每次调用只针对一个 `fileId`，`tagIds` 不能为空，且必须是你团队的云存储标签。浏览器标签会被拒绝。 - **副作用**：请求中未出现的标签会从文件上移除，缺少的会被补上。**本接口无法清空全部标签**，因为空列表会被拒绝。 - **完成信号**：同步，相同请求体幂等。 已记录的业务错误码：`39011`, `39048`, `390
 - [POST /api/cloudstorage/file/tag/add](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-file-tags/addcloudstoragefiletagslocal.md): 为云存储文件追加标签，不移除已有标签。 - **前置条件**：每次调用只针对一个 `fileId`，`tagIds` 不能为空，且必须是你团队的云存储标签。 - **副作用**：只做追加，已有标签保持不变。要整体替换请用覆盖版接口。 - **完成信号**：同步且幂等——追加文件已有的标签不会产生任何变化。 已记录的业务错误码：`39011`, `39048`, `39049`。 各错误码的含义见
 - [POST /api/cloudstorage/file/tag/query](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-file-tags/querycloudstoragefiletagslocal.md): 返回一个或多个云存储文件上挂载的标签。 - **前置条件**：每个 `fileId` 都必须能在你的团队中解析；**只要有一个未知 ID，整个调用就失败**，不会返回部分数据。 - **副作用**：无。只读。可带退避安全重试。 - **注意**：`tagIds` 读自关联关系，而标签详情来自现存标签，所以一个仍挂在文件上却已被删除的标签会出现在 `tagIds` 里而在详情中没有对应项。两个数组长
 - [GET /api/cloudstorage/tag/all](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-file-tags/queryallcloudstoragefiletagslocal.md): 返回团队内所有云存储文件标签。 - **副作用**：无。只读。可带退避安全重试。 - **说明**：本接口**不分页，且云存储标签没有服务端数量上限**，因此响应体会随团队创建的标签数增长。
 - [POST /api/cloudstorage/tag/create](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-file-tags/createcloudstoragefiletaglocal.md): 创建一个云存储文件标签。 - **前置条件**：`tagName` 不能为空。 - **副作用**：创建标签，颜色从固定色板中选取。**不校验重名，也没有数量上限**，因此重复调用会创建出第二个同名标签。 - **完成信号**：同步；响应携带新建的标签。
 - [POST /api/cloudstorage/tag/edit](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-file-tags/editcloudstoragefiletaglocal.md): 重命名一个云存储文件标签。 - **前置条件**：标签必须存在于你的团队，且必须是云存储标签。 - **副作用**：只改名称；颜色和所有已有关联都保留，因此文件会立即显示新名称。 - **完成信号**：同步。没有乐观锁——并发重命名是后写覆盖。
 - [POST /api/cloudstorage/tag/delete/batch](https://guide.morelogin.com/zh/api-reference/cloud-storage/local-api/cloud-storage-file-tags/deletecloudstoragefiletagslocal.md): 删除云存储文件标签。 - **前置条件**：每个 ID 都必须是你团队的云存储标签；**只要有一个无效，整批都会失败**。 - **副作用**：标签被删除，但**它们与文件的关联不会被清理**。会有两个可预期的后果：`/cloudstorage/file/tag/query` 仍会返回已删除的标签 ID 且详情里没有对应项；`/cloudstorage/file/page` 的 `tagInfo`