创建 Data Bundle

在上传采集数据之前，你需要一个绑定到特定采集设备的空 Data Bundle。创建是一个两步流程：获取 Data Bundle 设备输入树，然后使用你所选叶子设备的完全解析后的 dbuPath 创建 Bundle。输入树通过一次调用返回；在本地遍历它（按 name 和 children）直到到达叶子。叶子节点携带你在创建时传入的 dbuPath 字符串；分支节点的 dbuPath 为 null。

---

端点

方法	路径	作用域	用途
GET	/v1/organization/{organizationId}/data-bundle-input-tree	read:bundle	获取设备输入树
POST	/v1/nodes/{parentId}/bundle	write:bundle	创建 Data Bundle

步骤 1：获取输入树

GET {api_url}/v1/organization/{organizationId}/data-bundle-input-tree
Authorization: Bearer {access_token}

响应是一棵嵌套树。每个节点包括：

字段	含义
name	用于构建路径的稳定标识符
label	便于阅读的显示名称
isLeaf	当节点是可选择的采集设备时为 true
dbuPath	叶子节点上完全解析的设备路径；分支上为 null
children	子节点（叶子上为空数组）

示例（已截断）：

{
  "nodes": [
    {
      "name": "POINTCLOUD",
      "label": "Point Cloud",
      "isLeaf": false,
      "dbuPath": null,
      "children": [
        {
          "name": "ZF",
          "label": "ZF",
          "isLeaf": false,
          "dbuPath": null,
          "children": [
            {
              "name": "ZFSLAM",
              "label": "ZF SLAM",
              "isLeaf": true,
              "dbuPath": "POINTCLOUD/ZF/ZFSLAM",
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

遍历树直到 isLeaf 为 true，然后复制 dbuPath（此处为 POINTCLOUD/ZF/ZFSLAM）。

步骤 2：创建 Bundle

在你拥有权限的父节点（通常是站点或文件夹）下创建 Bundle。传入 Bundle 名称和步骤 1 中的叶子 dbuPath。

POST {api_url}/v1/nodes/{parentId}/bundle
Authorization: Bearer {access_token}
Content-Type: application/json

{ "name": "ZF capture 2026-06-01", "dbuPath": "POINTCLOUD/ZF/ZFSLAM" }

{
  "id": "a6f75b3c-f261-4b27-9a2a-9a6cc1234c53",
  "name": "ZF capture 2026-01-01",
  "dbuPath": "POINTCLOUD/ZF/ZFSLAM"
}

将返回的 id 用作上传、处理和下载步骤的 bundleId。

错误情况

状态	原因
400 Bad Request	dbuPath 未知、不是叶子或不可用
403 Forbidden	对父节点没有权限，或没有内容访问权限

完整示例

import requests

API_URL = "https://<your-regional-api-url>"
TOKEN = "<access_token>"
ORG_ID = "<organization_id>"
PARENT_ID = "<site-or-folder-id>"

headers = {"Authorization": f"Bearer {TOKEN}"}

tree = requests.get(
    f"{API_URL}/v1/organization/{ORG_ID}/data-bundle-input-tree",
    headers=headers,
).json()

# Walk the tree to find the ZF SLAM leaf (your navigation logic may differ).
def find_dbu_path(nodes, *path):
    node = nodes
    for segment in path:
        node = next(n for n in node if n["name"] == segment)
        node = node["children"]
    leaf = node[0]
    assert leaf["isLeaf"]
    return leaf["dbuPath"]

dbu_path = find_dbu_path(tree["nodes"], "POINTCLOUD", "ZF", "ZFSLAM")

bundle = requests.post(
    f"{API_URL}/v1/nodes/{PARENT_ID}/bundle",
    headers=headers,
    json={"name": "ZF capture 2026-01-01", "dbuPath": dbu_path},
).json()

bundle_id = bundle["id"]
print(f"Created bundle {bundle_id} for device {bundle['dbuPath']}")

下一步

拿到 bundleId 后，继续前往向 Data Bundle 上传数据。