lakeFS Java SDK 中的 ImportCreation:对象存储数据导入请求模型详解
lakeFS Java SDK 中的 ImportCreation:对象存储数据导入请求模型详解
导读
本文聚焦 lakeFS Java SDK 中负责发起对象存储导入任务的请求模型 ImportCreation,它是调用 POST /repositories/{repository}/branches/{branch}/import 接口(ImportApi#importStart)时提交的核心请求体。读完本文,你将掌握 ImportCreation 的 paths、commit、force 三个字段的语义与使用约束,理解它与 ImportLocation、CommitCreation 的嵌套关系,并通过源码了解 lakeFS 服务端处理导入请求的完整链路。
ImportCreation 在 lakeFS 数据导入体系中的定位
lakeFS 的"导入"(Import)能力允许用户把外部对象存储(如 S3、GCS、Azure Blob)中已有的数据,以不复制对象本体的方式注册进 lakeFS 仓库的某个分支,并随之生成一次提交,从而让这些数据立即获得版本控制能力。整个导入流程由三个接口组成(见 ImportApi.md):
| 接口 | HTTP 方法与路径 | 说明 |
|---|---|---|
importStart |
POST /repositories/{repository}/branches/{branch}/import |
提交导入请求,请求体即 ImportCreation,返回 ImportCreationResponse |
importStatus |
GET /repositories/{repository}/branches/{branch}/import |
查询导入任务进度,返回 ImportStatus |
importCancel |
DELETE /repositories/{repository}/branches/{branch}/import |
取消进行中的导入任务 |
ImportCreation 就是其中 importStart 的请求体模型,是整个导入功能的"入口单据"。在 OpenAPI 规范 swagger.yml 中,它被定义为包含两个必填字段(paths、commit)和一个可选字段(force)的对象。
字段详解
ImportCreation 共三个字段,完整定义如下(源自 ImportCreation.md 及 Java 实现 ImportCreation.java):
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
paths |
List<ImportLocation> |
是 | 导入源位置列表,可同时导入多个源 |
commit |
CommitCreation |
是 | 导入完成后自动生成的提交(commit)的创建参数 |
force |
Boolean |
否 | 是否强制写入,默认 false |
从 ImportCreation.java 的校验逻辑可以看出服务端对字段的硬性要求:paths 和 commit 同时出现在 openapiRequiredFields 中,即请求体中二者缺一不可;而 force 未在必填集合内。反序列化时,如果请求缺少必填字段或 paths 不是 JSON 数组,会抛出 IllegalArgumentException。
paths:导入源与目标映射列表
paths 是一个 ImportLocation 数组。每个 ImportLocation(见 ImportLocation.md)包含三个字段:
| 字段名 | 类型 | 说明 |
|---|---|---|
type |
TypeEnum |
路径类型,取值为 common_prefix 或 object |
path |
String |
源位置,指向一个 common_prefix(前缀)或单个 object(对象),必须匹配 lakeFS 安装所配置的 blockstore 类型,例如 s3://my-bucket/production/collections/ |
destination |
String |
导入对象在目标分支上的位置。若 type 为 object,则是该对象在分支下的精确对象名;若为 common_prefix,则是分支下的前缀 |
TypeEnum 的可选值在 swagger.yml 中限定为 common_prefix 与 object 二选一。这两个类型对应服务端 pkg/catalog/catalog.go 中定义的 ImportPathTypePrefix 与 ImportPathTypeObject(见 catalog.go),GetImportPathType 会校验传入的字符串是否合法。
swagger.yml 给出了一个同时使用两种类型、双路径的示例请求体(见 swagger.yml):
{
"commit": {
"message": "Importing collections from S3"
},
"paths": [
{
"path": "s3://my-bucket/production/collections/",
"destination": "collections/",
"type": "common_prefix"
},
{
"path": "s3://my-bucket/production/collections/file1",
"destination": "collections/file1",
"type": "object"
}
]
}
该示例同时演示了两种典型用法:用 common_prefix 一次导入整个目录树,用 object 精确导入单个文件。
commit:导入提交的创建参数
commit 字段类型为 CommitCreation(见 CommitCreation.md),用于描述导入任务完成后自动创建的提交:
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
message |
String |
是 | 提交信息 |
metadata |
Map<String, String> |
否 | 附加元数据键值对 |
date |
Long |
否 | 覆盖提交创建时间(Unix 时间戳,秒) |
allowEmpty |
Boolean |
否 | 是否允许提交不包含任何变更 |
force |
Boolean |
否 | 提交强制选项 |
服务端会把 message 与 metadata 带入最终的提交记录:在 controller.go 中,body.Commit.Message 与 body.Commit.Metadata 被提取进 catalog.ImportCommit;若用户未填写 message,服务端会在 catalog.go 自动使用默认提交信息 "Import objects"。提交者(committer)则由服务端从当前认证用户中解析,客户端无需也不应指定。
force:强制写入开关
force 为可选布尔字段,默认 false(ImportCreation.java)。服务端在 controller.go 通过 swag.BoolValue(body.Force) 读取其值,并一路透传到 range/metarange 写入(graveler.WithForce(params.Force),见 catalog.go)与提交创建(catalog.go),用于控制底层写入操作是否允许强制覆盖已存在的对象。
完整的导入调用链:请求、轮询、取消
ImportCreation 仅用于发起导入。一次完整的导入实践通常包含三步:
- 发起:调用
importStart(repository, branch, importCreation),成功时返回 HTTP202 Accepted及ImportCreationResponse,其中id字段是导入进程的唯一标识(见 ImportCreationResponse.md)。 - 轮询:携带上一步拿到的
id调用importStatus(repository, branch, id),通过返回的ImportStatus判断进度。ImportStatus(见 ImportStatus.md)包含completed、updateTime、ingestedObjects(已处理对象数)、metarangeId、commit与error等字段。 - 取消:需要中止时调用
importCancel(repository, branch, id),成功返回 HTTP204 No Content。
Java SDK 调用示例
以下代码演示用 Java SDK 构造 ImportCreation 并启动一次导入(认证与客户端配置部分参照 ImportApi.md):
// Import classes:
import io.lakefs.clients.sdk.ApiClient;
import io.lakefs.clients.sdk.ApiException;
import io.lakefs.clients.sdk.Configuration;
import io.lakefs.clients.sdk.auth.*;
import io.lakefs.clients.sdk.ImportApi;
import io.lakefs.clients.sdk.model.*;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("http://localhost:8000/api/v1");
// 认证方式三选一:basic_auth / cookie_auth / jwt_token
HttpBasicAuth basic_auth = (HttpBasicAuth) defaultClient.getAuthentication("basic_auth");
basic_auth.setUsername("YOUR USERNAME");
basic_auth.setPassword("YOUR PASSWORD");
ImportApi apiInstance = new ImportApi(defaultClient);
String repository = "my-repo";
String branch = "main";
// 1. 构造导入源
ImportLocation loc = new ImportLocation()
.path("s3://my-bucket/production/collections/")
.destination("collections/")
.type(ImportLocation.TypeEnum.COMMON_PREFIX);
// 2. 构造提交参数
CommitCreation commit = new CommitCreation()
.message("Importing collections from S3");
// 3. 组装 ImportCreation 请求体
ImportCreation importCreation = new ImportCreation()
.addPathsItem(loc)
.commit(commit)
.force(false);
try {
// 发起导入,返回进程 id
ImportCreationResponse resp = apiInstance
.importStart(repository, branch, importCreation)
.execute();
String id = resp.getId();
System.out.println("Import started, id=" + id);
// 轮询状态直至完成
ImportStatus status;
do {
Thread.sleep(5000);
status = apiInstance.importStatus(repository, branch, id).execute();
System.out.println("ingested objects: " + status.getIngestedObjects());
} while (!Boolean.TRUE.equals(status.getCompleted()));
} catch (ApiException e) {
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
e.printStackTrace();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
}
SDK 侧对请求体的序列化与校验由 Gson 驱动:ImportCreation 内建的 CustomTypeAdapterFactory(见 ImportCreation.java)在序列化时剔除 additionalProperties,在反序列化时先调用 validateJsonElement 校验必填字段,再通过 fromJson/toJson 与 JSON 字符串互转(ImportCreation.java)。
服务端如何消费 ImportCreation:源码级原理
权限校验
服务端 ImportStart 处理器(controller.go)对请求做组合权限校验:调用方必须同时拥有目标分支的 WriteObjectAction 与 CreateCommitAction;此外,对 paths 中每个源,还需具备对应源位置的 ImportFromStorageAction 与目标位置的 WriteObjectAction。这意味着 paths 列表的每一项都会参与权限判定。
路径安全校验与存储类型检查
- 存储支持检查:lakeFS 会通过
GetStorageNamespaceInfo检查当前仓库的存储后端是否支持导入,若不支持(ImportSupport == false)则直接返回403 Forbidden(controller.go)。 - 路径合法性:
verifyImportPaths(catalog.go)禁止导入源位于仓库自身存储命名空间内部或包含仓库命名空间,防止把 lakeFS 管理的对象误当成外部数据导入。
异步执行与状态持久化
Import(catalog.go)首先为任务生成唯一 ID(基于 xid),把初始状态写入 KV 存储(避免返回响应后状态不可见,即代码注释提到的 race condition 问题),随后异步执行真正的导入:importAsync(catalog.go)为每个 paths 项创建对象存储 walker 与 WalkEntryIterator,并行摄取对象,然后写入 range、合并 metarange,最后调用 Store.Import 生成提交并更新状态为 completed。这也是为什么 importStart 返回 202 Accepted 而非 200——导入是后台任务,需要配合 importStatus 轮询。
取消语义
CancelImport(catalog.go)会先检查任务状态:若任务已完成则返回冲突错误(graveler.ErrConflictFound),否则把错误标记为 ImportCanceled 写入 KV 存储,使异步任务感知取消并中止后续写入。
小结
ImportCreation 是 lakeFS 数据导入功能的请求载体:paths 声明"从哪里导、导到哪"(支持 common_prefix 与 object 两种粒度),commit 定义导入完成后自动提交的元信息,force 控制底层写入是否允许强制覆盖。理解这个模型,配合 importStart / importStatus / importCancel 三个接口,即可用 Java SDK 完整驱动 lakeFS 的对象存储数据导入流程。相关模型与接口文档可继续阅读 ImportApi.md、ImportLocation.md、CommitCreation.md、ImportStatus.md 与 ImportCreationResponse.md;服务端实现细节可参考 pkg/api/controller.go 与 pkg/catalog/catalog.go。