Data Bundle 简介

Data Bundle 是一次采集的容器：原始输入文件（点云、轨迹、图像等）以及平台从这些文件生成的处理后输出。RealityConnect API 公开了 Prevu3D UI 所使用的相同的 Bundle 生命周期，因此集成无需浏览器即可创建 Bundle、上传数据、启动处理、跟踪进度以及检索输入文件。

本文档假定你已完成某个 OAuth 流程，并持有 access_token、你的区域 api_url 以及 organization_id。如果尚未完成，请参阅流程指南。

所有 Data Bundle 工作流端点（/v1/bundles/...、/v1/organization/.../data-bundle-input-tree 和 /v1/nodes/.../bundle）都被标记为实验性。在它们升级为稳定版之前，请预期契约会发生变化。请参阅实验性端点。

所需作用域

作用域	用于
read:bundle	获取设备输入树、列出上传会话、列出处理选项、列出处理记录、列出输入文件下载 URL
write:bundle	创建 Bundle、打开并完成上传会话、启动处理

你还需要对创建 Bundle 的父节点具有内容访问权限和节点权限，并在后续步骤中对 Bundle 本身具有相应权限。

端到端流程

flowchart LR
  A["1. Get input tree"] --> B["2. Create bundle"]
  B --> C["3. Upload input files"]
  C --> D["4. List processing options"]
  D --> E["5. Start processing"]
  E --> F["6. Poll processing records"]

每个编号步骤对应一个专属指南：

步骤	指南	摘要
1–2	创建 Data Bundle	获取设备输入树、选择叶子 dbuPath、在父节点下创建 Bundle
3	向 Data Bundle 上传数据	打开上传会话、将每个文件分段上传到 S3、完成上传
4–6	处理与监控	列出可用输出、启动处理、轮询直到每个作业达到终态

下载输入文件是可选的：仅当你需要再次检索 Bundle 已上传的输入文件时才使用它。

验证模型

结构规则（强制文件类型、允许的扩展名、跨类型依赖、多重性）在你打开上传会话时返回的 requirements 数组中描述。在上传之前以及启动处理之前遵循该结构是用户的责任。

上传 API 会将每个文件记录在你提供的 type 下，并且仅根据数量完成会话。深层内容验证（.las 是否为真正的设备采集、元数据 JSON 是否正确引用其图像）发生在启动处理之后，而非上传时。命名正确但格式错误的文件会毫无报错地上传，稍后在处理过程中失败。

由于上传结构不正确（缺少强制类型、依赖被破坏、扩展名错误等）而导致的处理失败将不予退款。