# 管理文件存储

在数据库中创建和维护根卷与文件，并查看文件产物。卷属于数据库；表及表数据请转到[管理目录、数据库和表](catalog-databases-tables.md)。

控制台数据库加号中的存储对象是「卷」。卷文件列表里 `file_type` 为 `folder` 的条目对应「打开文件夹」，见[查看文件列表](../../../../reference/api/ai-studio/resource-center/catalog/list-files.md)。

## 前提条件

- 准备目标工作区的访问条件；通用规则见[调用前准备](../../api-call-basics.md)。
- 创建卷前，已确定其所属数据库。
- 将上传的文件关联到卷前，已取得上传后生成的文件记录和目标卷。

## 调用顺序

1. 先从 Catalog 层级中确定目标数据库；需要新存储位置时，在该数据库中创建根卷，并保留卷 ID。
2. 通过卷 ID 查看文件列表，确认操作位置。需要新增子层级时，在卷或现有文件夹下创建文件夹；列表中的 `folder` 条目仍在同一卷下，再次查询时保留 `volume_id` 并传入 `parent_id`。
3. 上传文件后，使用创建文件操作将已有文件记录关联到目标卷；随后查看文件详情或文件列表确认关联结果。需要修改文件夹时先确认其位置。
4. 需要检查内容时，预览或下载文件；需要检查多个文件的处理结果时，批量查看文件处理关联或数据资产。
5. 解除引用、清空或删除前，先查看目标详情和引用关系。删除卷、文件夹或文件后，重新查询可用资源确认结果。

## API 操作

### 创建和维护卷

| 要完成的事 | API 操作 | 何时使用 |
| --- | --- | --- |
| 创建卷 | [创建卷](../../../../reference/api/ai-studio/resource-center/catalog/create-volume.md) | 已确定目标数据库，需要建立根卷时使用。 |
| 查询卷详情 | [查看卷详情](../../../../reference/api/ai-studio/resource-center/catalog/get-volume.md) | 确认目标根卷的当前信息时使用。 |
| 查询卷完整路径 | [查看卷完整路径](../../../../reference/api/ai-studio/resource-center/catalog/get-volume-path.md) | 需要确认卷在 Catalog 层级中的位置时使用。 |
| 更新卷 | [更新卷](../../../../reference/api/ai-studio/resource-center/catalog/update-volume.md) | 修改卷的名称或描述时使用。 |
| 删除卷 | [删除卷](../../../../reference/api/ai-studio/resource-center/catalog/delete-volume.md) | 已处理卷内文件后删除根卷时使用。 |
| 查看卷引用 | [查看卷引用](../../../../reference/api/ai-studio/resource-center/catalog/list-volume-references.md) | 调整或删除卷前检查引用关系时使用。 |

### 管理文件夹

| 要完成的事 | API 操作 | 何时使用 |
| --- | --- | --- |
| 创建文件夹 | [创建文件夹](../../../../reference/api/ai-studio/resource-center/catalog/create-folder.md) | 需要在卷或现有文件夹下创建子文件夹时使用。 |
| 更新文件夹 | [更新文件夹](../../../../reference/api/ai-studio/resource-center/catalog/update-folder.md) | 需要修改文件夹信息时使用。 |
| 查看文件夹引用 | [查看文件夹引用](../../../../reference/api/ai-studio/resource-center/catalog/list-folder-references.md) | 调整、清空或删除文件夹前检查引用关系时使用。 |
| 清空文件夹 | [清空文件夹](../../../../reference/api/ai-studio/resource-center/catalog/empty-folder.md) | 需要删除指定文件夹及其子文件夹中的内容时使用。 |
| 删除文件夹 | [删除文件夹](../../../../reference/api/ai-studio/resource-center/catalog/delete-folder.md) | 确认目标文件夹不再需要时使用。 |

### 上传、关联和访问文件

| 要完成的事 | API 操作 | 何时使用 |
| --- | --- | --- |
| 上传文件 | [上传文件](../../../../reference/api/ai-studio/resource-center/catalog/upload-file.md) | 先上传一个尚未关联到卷的文件时使用。 |
| 创建文件 | [创建文件](../../../../reference/api/ai-studio/resource-center/catalog/create-file.md) | 将已有文件记录关联到指定卷时使用。 |
| 查询文件列表 | [查看文件列表](../../../../reference/api/ai-studio/resource-center/catalog/list-files.md) | 按卷确认当前文件，或打开列表中的文件夹条目时使用。 |
| 查询文件详情 | [查看文件详情](../../../../reference/api/ai-studio/resource-center/catalog/get-file.md) | 确认文件当前信息或后续操作目标时使用。 |
| 更新文件 | [更新文件](../../../../reference/api/ai-studio/resource-center/catalog/update-file.md) | 需要提交文件更新请求时使用。 |
| 预览文件 | [预览文件](../../../../reference/api/ai-studio/resource-center/catalog/preview-file.md) | 需要以内联内容检查文件时使用。 |
| 下载文件 | [下载文件](../../../../reference/api/ai-studio/resource-center/catalog/download-file.md) | 需要取得文件内容时使用。 |
| 解除文件引用 | [解除文件引用](../../../../reference/api/ai-studio/resource-center/catalog/unlink-file.md) | 需要解除同一根卷中一组文件的引用时使用。 |
| 删除文件 | [删除文件](../../../../reference/api/ai-studio/resource-center/catalog/delete-file.md) | 确认目标文件不再需要时使用。 |
| 触发文件工作流 | [触发文件工作流](../../../../reference/api/ai-studio/resource-center/catalog/trigger-file-workflow.md) | 需要为文件触发关联工作流时使用。 |

### 查看处理结果

| 要完成的事 | API 操作 | 何时使用 |
| --- | --- | --- |
| 查询文件产物 | [查看文件处理关联](../../../../reference/api/ai-studio/resource-center/catalog/list-file-artifacts.md) | 按文件 ID 查询文件产物信息时使用。 |
| 查询数据资产 | [查看数据资产](../../../../reference/api/ai-studio/resource-center/catalog/get-data-asset.md) | 按原始文件 ID 查询处理后的数据资产时使用。 |
| 批量查看文件处理关联 | [批量查看文件处理关联](../../../../reference/api/ai-studio/resource-center/catalog/batch-resolve-file-artifacts.md) | 需要一次查询多个文件的处理关联时使用。 |
| 批量查看数据资产 | [批量查看数据资产](../../../../reference/api/ai-studio/resource-center/catalog/batch-get-data-assets.md) | 需要一次读取多个原始文件的数据资产时使用。 |

## 结果确认

通过[查看卷详情](../../../../reference/api/ai-studio/resource-center/catalog/get-volume.md)、[查看文件详情](../../../../reference/api/ai-studio/resource-center/catalog/get-file.md)或[查看文件列表](../../../../reference/api/ai-studio/resource-center/catalog/list-files.md)确认创建、关联和更新结果。文件处理结果以文件产物和数据资产查询结果为准。

## 限制和注意事项

- 查询文件列表时必须且只能按一个 `volume_id` 筛选；打开文件夹条目时仍须保留该 `volume_id`。
- 上传文件不会自动关联到卷，需再调用创建文件操作。
- 未处理的文件不会出现在数据资产查询结果中。
- 删除卷前应处理卷内文件；解除引用的一组文件必须属于同一个根卷。
- 更新文件接口当前不会持久化名称变更；不要将成功响应视为文件名已经更新。

## 下一步

- [管理目录、数据库和表](catalog-databases-tables.md)