目录、数据库、表、卷和文件¶
Product SDK 将数据资源组织在工作区范围内。先取得 SDK 返回的工作区对象，再从目录进入数据库、表、卷、文件夹和文件；不要在应用中拼接资源路径或根据显示名称猜测资源 ID。
选择起点¶
要完成的任务 |
从哪里开始 |
结果 |
|---|---|---|
使用已有的目录、数据库或表 |
工作区对象和已确认的资源 ID |
对应的目录、数据库或表对象 |
查找目录，不存在时创建 |
工作区的目录准备方法 |
目录对象；缺少目录时会产生创建操作 |
查找卷，不存在时创建 |
数据库的卷准备方法 |
卷对象；缺少卷时会产生创建操作 |
上传已有的字节内容 |
卷对象 |
文件对象 |
“按名称准备”会查找完全匹配的可见资源；找不到时会创建资源。自动化脚本使用这类方法前，应确认名称、目标工作区和写入权限。
SDK 调用¶
以下示例从已经取得的工作区对象开始，依次取得目录、数据库和卷，再上传调用方已持有的字节内容：
catalog, err := workspace.PrepareCatalog(ctx, catalogName)
database, err := catalog.PrepareDatabase(ctx, databaseName)
volume, err := database.PrepareVolume(ctx, volumeName)
file, err := volume.UploadBytesHandle(ctx, fileName, fileBytes)
catalog = workspace.prepare_catalog(catalog_name)
database = catalog.prepare_database(database_name)
volume = database.prepare_volume(volume_name)
file = volume.upload_bytes_handle(file_name, file_bytes)
file 是后续下载、预览或数据血缘操作使用的文件对象。上传调用已提交后，仍应根据返回结果确认文件可用状态。
管理表¶
通过目录和数据库对象浏览表，或使用已确认的表 ID 获取表对象。创建表时，调用方需要明确提供表名和列定义；SDK 不会根据展示名称、文件名或查询文本推断表结构。
创建、更新、清空或删除表会改变数据。将这些操作与只读浏览分开，并在调用前保留用于确认的目录、数据库和表信息。
管理卷和文件¶
卷用于组织文件资源，文件夹和文件都属于明确的卷作用域。上传时应由调用方提供文件名和字节内容；上传成功后保存返回的文件对象或文件 ID，以便后续预览、下载、删除或触发关联操作。
不要让应用根据本地目录自动发现文件、根据文件名推断目标卷，或把文件 URL 当作永久资源标识。文件来源、目标卷和后续写入操作都应由调用方明确选择。
语言方法对照¶
任务 |
Go |
Python |
|---|---|---|
按名称准备目录 |
|
|
按名称准备卷 |
|
|
上传已有字节并取得文件对象 |
|
|
这些方法返回的 SDK 对象会保留已知的资源作用域。后续调用优先复用这些对象，不要回退为手写接口路径。