PAYATHON 2026

Forma API 中 sheetlineage 的实体 id 为何与 sheet id 不匹配？

排障赵师傅

结论

sheetlineage.id 是图纸的历史标识（Sheet history ID），与 Sheets API 返回的 sheet.id 含义不同，不能直接比较。

要找到对应图纸，可以通过 Data Connector API 导出 sheets 数据，用 Relationship 中的 sheetlineage.id 匹配 sheets.history_id。匹配记录的 id 就是对应的 sheet ID。标识含义及处理方式说明

为什么两个 ID 不相等

这些字段标识的对象不同：

字段含义
Relationship 顶层的 id关系记录本身
type: "sheetlineage" 实体的 id图纸历史标识
Sheets API 返回的 sheet.id具体图纸记录
Data Connector 的 sheets.history_id该图纸所属的历史标识

Data Connector 的官方 schema 同时提供 sheets.id 和 sheets.history_id，其中 history_id 指向图纸所属的历史记录。version_set_id、is_current 和 deleted 则可用于区分版本和状态。Sheets 数据结构

Docs 文件关联中的 ID 对应关系不能直接套用于 sheetlineage。处理 Relationships 时，需要结合实体的 domain 和 type 判断 id 的含义。

如何找到对应的 sheet

  1. 从 Relationship 的 entities 中找到 domain 为 autodesk-construction-sheet、type 为 sheetlineage 的实体，取出其 id。
  2. 通过 Data Connector API 提交数据提取请求，将 serviceGroups 设置为 ["sheets"]，并限定目标项目。
  3. 等待后台提取任务完成后，下载结果，找到 sheets 表对应的数据文件。提交请求时收到的响应不是图纸数据。Data Connector 提取流程
  4. 在同一账户、同一项目内，查找 history_id 等于该实体 ID 的记录，取出记录的 id。
  5. 如果匹配到多条记录，先保留全部结果，再按业务需求选择当前版本或指定的 version set。

示例中的匹配条件为：

sheets.history_id = "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0"

查询示例

如果已将导出的 sheets 数据导入数据库，且表名为 sheets，可以使用参数化 SQL 查询：

SELECT
    id AS sheet_id,
    history_id,
    name,
    title,
    version_set_id,
    is_current,
    deleted
FROM sheets
WHERE bim360_account_id = :account_id
  AND bim360_project_id = :project_id
  AND history_id = :sheetlineage_id;

将 :sheetlineage_id 绑定为示例中的 UUID，并按所用数据库驱动调整参数占位符语法。

拿到 sheet_id 后，就可以与 Sheets API 列表中的 results[].id 对应。核对历史版本时，可以这样请求：

curl --get \
  "https://developer.api.autodesk.com/construction/sheets/v1/projects/${PROJECT_ID}/sheets" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "currentOnly=false" \
  --data-urlencode "collectionId=*" \
  --data-urlencode "limit=100"

该请求只返回一页结果，需要沿响应中的 pagination.nextUrl 继续请求，直到没有下一页。currentOnly=false 用于包含历史版本，collectionId=* 用于覆盖所有 collections。GET sheets 参数说明

注意事项

  • Sheets API 当前公开的响应结构未列出图纸历史标识字段。如果实际响应中也没有该字段，仅遍历 sheet.id 无法完成映射。
  • 同一个 history_id 可能匹配多个图纸版本。查询当前图纸时，检查 is_current；追溯历史时，结合 version_set_id 选择记录，不要直接取第一条。
  • Sheets API 默认只返回当前、未删除的图纸。未指定 collectionId 时，只返回未分组 collection 的结果。核对已删除图纸时，需要另用 isDeleted=true 查询。GET sheets 筛选规则
  • Data Connector 的结果是提取时的数据快照。如果找不到记录，先检查项目范围、提取时间和任务是否成功，再判断是否存在数据缺失。

备注：内容仅供参考。