企业官网建设流程全解析

• 数据工程
• 数据湖
• 大数据
• 对象存储
• 后端

lakeFS 的ExperimentalApi是 Python SDK（lakefs_sdk）中面向实验性功能的 API 类，覆盖预签名分片上传（presign multipart upload）、Pull Request、外部主体认证与 STS 登录、分支硬重置、对象元数据重写等能力。本文以 ExperimentalApi.md 为骨架，结合服务端 Go 实现与端到端测试，完整讲解每个接口的 HTTP 语义、Python 调用签名、参数与状态码细节，帮助你直接写出可运行的调用代码，并理解其底层行为边界。

一、ExperimentalApi 是什么

ExperimentalApi是 lakeFS OpenAPI 规范（api/swagger.yml）在 Python 客户端中的自动生成实现，所有 URI 均相对于/api/v1。它由 OpenAPI Generator 生成，源码位于 clients/python/lakefs_sdk/api/experimental_api.py，并在 lakefs_sdk/init.py 中通过from lakefs_sdk.api.experimental_api import ExperimentalApi直接对外导出，因此使用方式与其他 API 类（如ObjectsApi、BranchesApi）完全一致。

该接口集合包含 16 个方法，覆盖四类主题：

服务端这些端点统一实现在 pkg/api/controller.go，权限动作定义在 pkg/permissions/actions.go，二者可作为理解接口行为与权限模型的直接依据。

二、公共调用模式：认证与客户端初始化

除external_principal_login与sts_login两个公开登录端点外，其余接口均需要认证。文档给出了三种认证方式，可同时配置、按需选用：

import os import lakefs_sdk # 方式一：HTTP Basic 认证（服务端账号密码） configuration = lakefs_sdk.Configuration( username=os.environ["USERNAME"], password=os.environ["PASSWORD"], ) # 方式二：API Key 认证（cookie_auth） configuration.api_key['cookie_auth'] = os.environ["API_KEY"] # 若需为 API Key 添加前缀（如 Bearer），取消下一行注释 # configuration.api_key_prefix['cookie_auth'] = 'Bearer' # 方式三：Bearer（JWT）令牌认证 configuration = lakefs_sdk.Configuration( access_token=os.environ["BEARER_TOKEN"], )

随后统一通过上下文管理器创建客户端与 API 实例：

with lakefs_sdk.ApiClient(configuration) as api_client: api_instance = lakefs_sdk.ExperimentalApi(api_client) # 调用各实验接口...

注意：Configuration.host默认即为/api/v1，在绝大多数真实部署场景下需要显式覆盖为完整的服务地址（如http://localhost:8000/api/v1），文档示例中的/api/v1仅是默认占位值。

三、预签名分片上传：绕过服务端直传对象存储

预签名分片上传是ExperimentalApi中工程价值最高的能力：它让客户端直接从浏览器或任意 HTTP 客户端把大对象分片写入对象存储，避免大文件流量经过 lakeFS 服务端，适合超大文件、跨地域上传等场景。

3.1 发起上传：create_presign_multipart_upload

接口create_presign_multipart_upload(repository, branch, path, parts=parts)对应POST /repositories/{repository}/branches/{branch}/staging/pmpu，返回PresignMultipartUpload对象。

• repository/branch：目标仓库与分支；
• path：相对于分支根目录的对象路径；
• parts：可选参数，需要返回的预签名 URL 数量（即预计的分片数），不传则只创建 uploadId 与物理地址、不生成 URL。

参数与返回类型详见 PresignMultipartUpload.md：

api_response = api_instance.create_presign_multipart_upload( repository, branch, path, parts=parts) pprint(api_response) # 包含 upload_id、physical_address、presigned_urls 列表

要点：

• 分片编号从 1 开始；
• 除最后一片外，每个分片都有最小大小限制，取决于底层对象存储实现——文档明确举例：使用 S3 blockstore 时最小分片为 5MB（最后一片除外）；
• 正常返回201 Created；空对象名/空仓库名/负数分片数返回400，未知分支返回404。

上述边界行为有端到端测试直接佐证：esti/presign_multipart_test.go 的TestCreatePresignMultipartUpload覆盖了空对象名、空分支、未知分支、空仓库、不传 parts、负数 parts 等用例，并断言成功时UploadId与PhysicalAddress非空、PresignedUrls长度与请求的 parts 一致。

3.2 获取单分片上传地址：upload_part 与 upload_part_copy

upload_part(repository, branch, upload_id, path, part_number, upload_part_from)对应PUT /repositories/{repository}/branches/{branch}/staging/pmpu/{uploadId}/parts/{partNumber}，返回UploadTo对象（含可用的预签名 URL），请求体为 UploadPartFrom.md：

api_response = api_instance.upload_part( repository, branch, upload_id, path, part_number, upload_part_from=lakefs_sdk.UploadPartFrom())

upload_part_copy(repository, branch, upload_id, path, part_number, upload_part_copy_from)对应同路径下的/copy子端点，通过 UploadPartCopyFrom.md 指定源对象，实现“从另一个对象复制部分数据作为本分片”的服务器端拷贝语义，返回204并携带ETag响应头，其余错误语义与upload_part一致。

3.3 完成与中止：complete / abort

complete_presign_multipart_upload(repository, branch, upload_id, path, complete_presign_multipart_upload=...)对应PUT .../staging/pmpu/{uploadId}，将所有已上传分片组装成对象，返回 ObjectStats.md：

api_response = api_instance.complete_presign_multipart_upload( repository, branch, upload_id, path, complete_presign_multipart_upload=lakefs_sdk.CompletePresignMultipartUpload())

请求体 CompletePresignMultipartUpload.md 用于提交物理地址与分片信息；成功返回200，若与已提交的 commit 冲突则返回409。

abort_presign_multipart_upload(repository, branch, upload_id, path, abort_presign_multipart_upload=...)对应DELETE .../staging/pmpu/{uploadId}，请求体 AbortPresignMultipartUpload.md，成功返回204。测试 esti/presign_multipart_test.go 验证了 abort 的空路径、空仓库、未知仓库、空 uploadId 等错误路径，并给出了“先 create 再 abort 完整对象”的可用闭环。

3.4 与 S3 网关的分片上传的异同

lakeFS 本身通过 S3 兼容网关支持标准CreateMultipartUpload/CompleteMultipartUpload流程（见 pkg/gateway/operations/postobject.go 的uploads与uploadId查询参数）。两者差异在于：网关模式由 lakeFS 代理组装分片，而ExperimentalApi的预签名模式把分片直传下沉到对象存储，服务端只负责登记与校验，天然适配浏览器直传等无法携带 AWS 签名的场景。

四、Pull Request 全生命周期管理

ExperimentalApi提供的 PR 接口允许在单个仓库内，以分支为源/目标创建数据协作流程。服务端实现位于 pkg/api/controller.go，权限动作pr:CreatePullRequest、pr:ReadPullRequest、pr:WritePullRequest、pr:ListPullRequests定义于 pkg/permissions/actions.go。

4.1 创建与查询

create_pull_request(repository, pull_request_creation)对应POST /repositories/{repository}/pulls，请求体为 PullRequestCreation.md（含title、description、source_branch、destination_branch），返回 PullRequestCreationResponse.md，其中携带新 PR 的 id：

api_response = api_instance.create_pull_request( repository, pull_request_creation=lakefs_sdk.PullRequestCreation()) pprint(api_response) # PullRequestCreationResponse(id=...)

成功返回201，目标冲突时返回409。从服务端看，创建时作者取自当前登录用户（user.Committer()），因此该接口必须携带认证信息。

get_pull_request(repository, pull_request)对应GET /repositories/{repository}/pulls/{pull_request}，返回完整 PullRequest.md，包含id、author、status、creation_date、source_branch、destination_branch、merged_commit_id、closed_date等字段；pull_request参数即 PR id，返回200。

4.2 列表与分页

list_pull_requests(repository, prefix=..., after=..., amount=100, status='all')对应GET /repositories/{repository}/pulls，返回 PullRequestsList.md：

服务端在 controller.go#L5602 处将这三个分页参数直接透传给c.Catalog.ListPullRequest，并通过Pagination结构返回has_more游标，配合after即可完成翻页。注意列表响应中的description字段会被置空（Description: nil），源码注释明确说明这是为了维持权限要求（列表权限低于详情读取权限）。

4.3 更新与合并

update_pull_request(repository, pull_request, pull_request_basic)对应PATCH /repositories/{repository}/pulls/{pull_request}，请求体为 PullRequestBasic.md（title、description、status），成功返回200。服务端将其转换为graveler.UpdatePullRequest后调用 Catalog 层更新。

merge_pull_request(repository, pull_request)对应PUT /repositories/{repository}/pulls/{pull_request}/merge，返回 MergeResult.md：

api_response = api_instance.merge_pull_request(repository, pull_request) pprint(api_response) # MergeResult(reference=...)

合并语义（见 controller.go#L5723-L5783)：

1. 读取 PR，校验其status == open，否则返回400；
2. 校验当前用户同时拥有目标分支的CreateCommit与仓库的WritePullRequest权限（NodeTypeAnd组合）；
3. 调用c.Catalog.Merge(ctx, repository, pr.Destination, pr.Source, ...)执行真正的分支合并；
4. 合并成功后把 PR 状态置为merged并记录merged_commit_id，返回合并后的 commit reference。

合并冲突时返回409（文档注明该响应 schema 即将从空MergeResult演进为 Error 格式），前置条件不满足返回412。

五、外部主体与 STS 登录：认证体系扩展

这组接口用于把外部身份体系（如企业 IdP、云厂商身份）映射到 lakeFS 用户，并为外部认证器与 STS（Security Token Service）登录预留接入点。相关权限动作auth:CreateUserExternalPrincipal、auth:DeleteUserExternalPrincipal、auth:ReadExternalPrincipal定义于 pkg/permissions/actions.go。

5.1 外部主体绑定管理

• create_user_external_principal(user_id, principal_id, external_principal_creation=...)：POST /auth/users/{userId}/external/principals，将外部主体（principal_id）绑定到指定用户，请求体 ExternalPrincipalCreation.md，成功返回201，与现有绑定冲突返回409；
• delete_user_external_principal(user_id, principal_id)：DELETE /auth/users/{userId}/external/principals，解绑，成功返回204；
• list_user_external_principals(user_id, prefix=..., after=..., amount=100)：GET /auth/users/{userId}/external/principals/ls，分页列出用户绑定的外部主体，返回 ExternalPrincipalList.md，分页参数语义与 PR 列表一致（prefix/after/amount）；
• get_external_principal(principal_id)：GET /auth/external/principals，按 id 查询单个外部主体详情，返回 ExternalPrincipal.md。

5.2 登录端点

• external_principal_login(external_login_information=...)：POST /auth/external/principal/login，使用外部认证器执行登录，请求体 ExternalLoginInformation.md，成功返回 AuthenticationToken.md（含token与token_expiration）；
• sts_login(sts_auth_request)：POST /sts/login，请求体 StsAuthRequest.md，同样返回AuthenticationToken。

这两个端点不需要认证（文档 Authorization 栏标注 “No authorization required”）。需要特别说明的是：在当前仓库的服务端实现中，ExternalPrincipalLogin 与 StsLogin 均直接返回 HTTP 501 Not Implemented，属于预留的实验性端点；authentication_token的响应结构可参考服务端其他登录端点（如 controller.go#L794-L798 的AuthenticationToken{Token, TokenExpiration}）。因此在当前版本中调用这两个接口会得到 501，使用时应将其视为“接口契约已定义、后端待实现”的实验能力。

六、分支硬重置与对象元数据重写

6.1 hard_reset_branch：分支强制重定位

hard_reset_branch(repository, branch, ref, force=False)对应PUT /repositories/{repository}/branches/{branch}/hard_reset，将分支指针强制重定位到指定引用：

文档明确约束：分支不能包含未提交数据，否则重置被拒绝。成功返回204；无权限返回403。服务端在 controller.go#L2918-L2932 将其映射为c.Catalog.HardResetBranch(ctx, repository, branch, params.Ref, graveler.WithForce(swag.BoolValue(params.Force)))，force通过 graveler 的WithForce选项控制是否允许带未提交数据执行。

6.2 update_object_user_metadata：整体重写对象用户元数据

update_object_user_metadata(repository, branch, path, update_object_user_metadata)对应PUT /repositories/{repository}/branches/{branch}/objects/stat/user_metadata：

该接口以“重写全部”为语义（文档描述为 rewrite (all) object metadata），即用请求体中的完整元数据集合替换对象现有的用户元数据，而非增量合并；成功返回201。适合批量修正对象的分类标签、数据血缘标记等场景。

七、实验接口使用清单与注意事项

在 ExperimentalApi.md 基础上，汇总所有端点的 HTTP 语义与典型返回码，便于快速检索：

实践建议：

• 预签名分片上传是目前最成熟、有完整测试背书的能力（测试见 esti/presign_multipart_test.go），可直接用于生产场景的大对象直传；分片大小规划务必遵守底层 blockstore 的最小分片限制；
• Pull Request 接口功能完整，合并流程复用 lakeFS 原生 merge 引擎，可直接基于它构建数据审批流；
• 外部主体 / STS 登录接口契约已由 OpenAPI 定义（对应端点路径见 pkg/api/apigen/lakefs.gen.go），但服务端当前仅返回 501，接入外部 IdP 前需确认目标 lakeFS 版本的后端支持情况；
• 所有写操作均受 pkg/permissions/actions.go 中定义的权限动作约束，实际调用前需为调用主体配置相应策略，否则会收到 403。

想要进一步阅读每个方法完整参数说明与模型字段定义，可直接查看 clients/python/docs 目录下对应的模型文档（如 PresignMultipartUpload.md、PullRequest.md），以及服务端实现 pkg/api/controller.go。

• 数据工程
• 数据湖
• 大数据
• 对象存储
• 后端